Skip to main content

Error Codes

Every error includes recovery_action (what to do next) and docs_url for AI Agent auto-handling.

{
  "error": "PROVIDER_RATE_LIMITED",
  "http_status": 429,
  "message": "Provider rate-limited the request for "openai-chat". Try again shortly.",
  "request_id": "req_abc123",
  "suggestion": "try_later",
  "recovery_action": "Wait 10-60s and retry, or use batch deduplication to reduce call volume.",
  "docs_url": "https://apitree.ai/docs/errors#rate-limit"
}

Error Code Catalog

Error Code
HTTP
Recovery Action
UNAUTHORIZED401Request a new API key and retry with Authorization: Bearer <key>
FORBIDDEN403Check plan tier or organization role; upgrade via /pricing
NOT_FOUND404Confirm API slug exists via GET /api/v1/apis?q=<term>
RATE_LIMIT_EXCEEDED429Back off and retry after Retry-After header. Upgrade tier for higher limits
PROVIDER_RATE_LIMITED429Provider rate-limited. Wait 10-60s, or use batch deduplication
AUTH_FAILURE401Provider rejected credentials. Verify/rotate via admin
PROVIDER_AUTH_REQUIRED401/403Provider rejected the unauthenticated call. Register your key at /settings/byok, then retry
PROVIDER_AUTH_REJECTED401/403Provider rejected your registered key. Check or rotate it at /settings/byok, verifying the auth method and header/query parameter name
INSUFFICIENT_CREDITS402Top up credits or upgrade plan at /pricing
PROVIDER_TIMEOUT504Upstream took too long. Retry once; consider alternative provider
PROVIDER_CIRCUIT_OPEN503Provider failing repeatedly. Wait ~30s for circuit reset
INVALID_BATCH400Batch body must be { calls: [{api, method?, path?, params?}] } with 1-10 entries
BATCH_TOO_LARGE400Split into multiple batches of at most 10 calls each
PAYLOAD_TOO_LARGE413Reduce request body below 1MB. Stream or paginate large payloads
CALL_FAILED502Inspect message field. If transient, retry with exponential backoff (max 3)

Legal Consent Errors (Signup)

POST /api/auth/signup validates the submitted consents[] array against legal/manifest.json (the current required documents, versions, and content hashes) — not against anything hardcoded in the client. These codes only ever come from that one endpoint.

Error Code
HTTP
When it happens / Recovery
CONSENT_REQUIRED422A required document (per manifest, e.g. terms/privacy) was omitted or submitted with agreed:false — omitting and declining are treated identically. Recovery: GET /api/v1/legal/documents?required_at=signup to fetch the current required documents (id/version/locale/content_hash/url), then resubmit signup with all required consents set to agreed:true.
CONSENT_VERSION_STALE409The submitted document version isn't the manifest's current version for that doc_id (e.g. you cached an old version client-side). Recovery: GET /api/v1/legal/documents/{id}/current/{locale} to get the current version + content_hash, then resubmit.
CONSENT_HASH_MISMATCH409The submitted content_hash doesn't match the server-rendered document for that version/locale (or the version/locale combination doesn't exist). Recovery: GET /api/v1/legal/documents/{id}/{version}/{locale} to get the exact content_hash, then resubmit that value unmodified.

All three errors follow the same recovery pattern: re-fetch the documents API, then resubmit signup with the fresh version/locale/content_hash. A 422/409 here never costs credits or creates a user row — the entire signup is rejected before any DB write.

Error Categories

  • • auth — 401/403: credential or permission issues
  • • rate_limit — 429: apitree tier or provider rate limit
  • • timeout — 504: provider too slow
  • • circuit — 503: provider failing, circuit breaker open
  • • billing — 402: insufficient credits
  • • client — 4xx: malformed request
apitree · AI-Native API Marketplace