Common failure categories
- authentication failure
- missing parameters or invalid payload shape
- quota exhaustion or throttling
- upstream model service failure
- file upload or media processing failure
Suggested debugging order
- verify auth headers, keys, and environment variables
- verify payload structure and field types
- confirm throttling, quota, or model availability issues
- review server logs and request tracing
Integration guidance
- keep request IDs in all error responses
- show user-friendly messages in the frontend and keep detailed errors in server logs
- normalize provider-specific errors into platform-level error codes when using a unified gateway