Error Codes Reference

Boundless API uses OpenAI-compatible error format. Errors return JSON:

Last updated: June 16, 2026

Boundless API uses OpenAI-compatible error format. Errors return JSON:

{
  "error": {
    "message": "Human-readable description",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

HTTP Status Codes

HTTP Meaning Billed?
200 Success Yes (per tokens)
400 Bad request — fix your payload No
401 Invalid or missing API key No
402 Insufficient credits No
403 Forbidden — model access denied No
404 Endpoint or model not found No
429 Rate limit exceeded No
500 Boundless internal error No
502 Upstream provider error No
503 Service temporarily unavailable No
529 Provider overloaded (retry) No

Error Codes

Authentication (401)

Code Message Cause Action
invalid_api_key Invalid API key Wrong or revoked key Check key in Dashboard
missing_api_key No Authorization header Forgot Bearer token Add Authorization: Bearer sk-...

Billing (402)

Code Message Cause Action
insufficient_quota Insufficient credits Balance zero or below minimum Add credits or enable auto-recharge
spend_limit_exceeded Spend limit reached Hard cap hit Raise limit in Settings

Request (400)

Code Message Cause Action
invalid_request_error Malformed request JSON/schema error Check request body
context_length_exceeded Too many tokens Input exceeds model context Reduce input or use larger context model
invalid_model Model not found Typo or deprecated model Check Models
model_not_found Model unavailable Model removed or restricted Choose alternative model

Access (403)

Code Message Cause Action
model_access_denied Model not allowed for account Starter tier restriction Purchase credits to unlock
region_restricted Model not available in region Geographic restriction Use allowed model or contact support

Rate Limits (429)

Code Message Cause Action
rate_limit_exceeded Too many requests RPM/TPM limit hit Back off, exponential retry
quota_exceeded Daily free limit Free model daily cap Add credits or wait 24h

Server (5xx)

Code Message Cause Action
internal_error Internal server error Boundless bug Retry; contact support with request ID
upstream_error Provider error Model provider issue Retry; check Status page
overloaded Service overloaded High load Retry with backoff

Retry Guidance

Error Retry? Backoff
429 Yes Exponential: 1s, 2s, 4s… max 60s
502, 503, 529 Yes 1–5 retries with jitter
400, 401, 402, 403 No Fix request first
500 Yes 1–2 retries, then support

Zero-Token Billing

You are not charged when:

  • Request fails before provider processing (4xx except where noted)
  • Provider returns error with zero completion tokens
  • Request times out with no tokens consumed

You are charged when:

  • Provider returns tokens (even if output is empty string with completion tokens > 0)

Getting Help

Include in support requests:

  • x-request-id header from response (if present)
  • Timestamp (UTC)
  • Model name
  • HTTP status and error code
  • API key prefix only (first 8 chars)

support@boundlessapi.com

Internal guide: error-codes-support-guide.md