Skip to main content
ApiGo model APIs use HTTP status codes to communicate request outcomes. The exact fields in an error response follow the compatibility protocol of the endpoint you call, while the status meanings and recommended actions remain consistent. Do not match complete error messages in application logic. Use the HTTP status first, followed by a structured error type or code when the response provides one.

​
HTTP status codes

StatusMeaningRecommended action
400The request is malformed, invalid, or unsupported by the selected model.Correct the request before retrying.
401The API key is missing, invalid, or disabled.Check the authentication method and API key.
402The account balance is insufficient. Some compatibility protocols use this status.Top up the account before retrying.
403The API key is valid but is not permitted to make this request.Check model permissions, IP allowlists, and key configuration.
404The requested model, task, or resource does not exist or is not accessible with this key.Check the model name, resource ID, and API key used to create the resource.
429A request-rate limit, insufficient balance, or API-key usage limit prevents the request.Depending on the error, retry with backoff, top up, change the limit, or wait for the next period.
503ApiGo or an upstream service is temporarily unable to process the request.Retry with exponential backoff and jitter.

​
Understand 402 and 429

402 and 429 can both indicate a usage or capacity constraint, but they require different actions:
  • Request-rate or concurrency limit: reduce the request rate and retry with exponential backoff.
  • Insufficient account balance: top up before retrying. Repeated automatic retries will not help.
  • API-key usage limit: raise the configured limit or wait for the current limit period to end.
Structured error fields differ between endpoints. Use the HTTP status together with the available error type or code and the error message to determine the specific cause. See Rate limits for additional guidance.

​
Response format

Error responses follow the compatibility protocol of the endpoint you call, not the protocol of the selected model or upstream service. As ApiGo adds models and upstream providers, you do not need to add provider-specific error branches. Compatibility protocols may use different fields such as type, code, or status. These fields do not form one universal enum across all endpoints.
InformationStability and usage
HTTP statusUse this as the first level of error handling.
Structured error type or codeFollow the API definition or SDK type for the current endpoint. Do not assume field names or values are identical across endpoints.
Error messageUse it for display and troubleshooting, not exact-string matching in application logic.
Additional diagnostic informationIt may be omitted or redacted and should not be a business-logic dependency.
Use the API definition or SDK types for the endpoint when handling its exact response structure.

​
Streaming requests

Streaming requests can fail in two ways:
  • If an error occurs before streaming begins, the API returns a normal HTTP error status and error body.
  • If an error occurs after streaming begins, the HTTP status may already be 200, and the error is delivered as an event inside the stream.
Continue reading the stream until it ends normally, and treat an in-stream error event as a failed request. Do not use the initial HTTP 200 alone as proof that a streaming request succeeded.

​
Retry and troubleshooting

  • Do not automatically retry 400, 401, 402, 403, or 404 unless you have corrected the underlying problem.
  • Automatically retry 429 only when it represents a request-rate limit. Balance and key-limit errors require an account or configuration change.
  • Retry 503 a limited number of times with exponential backoff and random jitter.
  • Record the request time, endpoint, HTTP status, and structured error type. Record x-apigo-request-id as well when the response provides one.
  • Never include complete API keys in logs or support requests.
To protect platform and upstream details, ApiGo normalizes some failures into a generic 503. These responses do not expose the internal or upstream cause.