Skip to main content

​
Error Handling

Every error response from the InfinityBlue API follows a single, OpenAI-compatible shape. Knowing the structure — and the meaning of the most common status codes — turns a broken request into a five-minute fix.

​
Error response shape

{
  "error": {
    "message": "Incorrect API key provided: sk-xxx***. You can find your API key at https://getinfinityblue.com.",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

message

A human-readable description of what went wrong. Safe to surface in logs and, in most cases, in user-facing error messages.

type

A coarse category such as invalid_request_error, authentication_error, rate_limit_error, or server_error. Use it to drive retry logic.

code

A stable machine-readable identifier. Codes do not change once published, so you can safely switch on them.

param

When the error is tied to a specific field, its JSON path is returned here. null means the error is not field-specific.

​
Common status codes

StatusTypeMeaningRecommended action
400invalid_request_errorMalformed body, missing field, or value outside the allowed range.Fix the request and retry. Do not retry blindly.
401authentication_errorMissing, malformed, or revoked API key.Re-check the key. See Authentication.
403permission_errorThe key does not have access to the requested model or feature.Upgrade the plan or pick a different model.
404not_found_errorThe endpoint or model does not exist.Verify the path and the model parameter.
413invalid_request_errorPayload is too large for the model.Reduce the input size, or chunk the content.
429rate_limit_errorYou exceeded the requests-per-minute or tokens-per-minute budget.Back off and retry with jitter. Honor the Retry-After header.
500server_errorAn upstream provider failed.Retry with exponential backoff.
502 / 503server_errorGateway or upstream is temporarily unavailable.Retry with backoff; the issue is on our side.
504server_errorThe upstream did not respond in time.Retry once or twice with backoff, then surface a friendly error.
The Retry-After header (in seconds) is the most reliable signal for 429 responses. Always honor it before falling back to your own backoff schedule.

​
Debugging checklist

1

Capture the full response

Log the status code, the JSON body, and the request ID returned in the x-request-id response header. Support can correlate the request ID with internal traces within minutes.
2

Reproduce with curl

Reproduce the failure with a minimal curl command. SDKs add retries, proxies, and middleware that obscure the real error.
3

Check `param` and `code`

If the error names a parameter, jump to that field in your payload. If it names a code, search the docs for the code string to find a known fix.
4

Check rate limits

Inspect the x-ratelimit-remaining-* and x-ratelimit-reset-* headers. A request can fail with 429 even when the body looks correct.
5

Open a support ticket

If the issue persists, include the request ID, the timestamp, and a redacted version of the payload. Never share the API key. Visit getinfinityblue.com for support options.

​
Building a robust client

A production client should:
  • Treat any 2xx as success.
  • Retry 429 and 5xx with exponential backoff and full jitter, capped at a small number of attempts.
  • Never retry 400, 401, 403, or 404 — these failures will not resolve on their own.
  • Surface a clear, user-friendly error when retries are exhausted, ideally using the gateway’s message.
  • Track the usage field of successful responses to keep your own cost telemetry accurate.