Error Handling

All OpenBits API responses follow a consistent envelope format. Errors include machine-readable codes for programmatic handling.

Response Format

Success

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "clxyz123abc",
    "cached": false
  }
}

Error

{
  "success": false,
  "error": {
    "statusCode": 401,
    "message": "Invalid API key",
    "code": "API_KEY_INVALID"
  }
}

Error Codes

Authentication Errors (4xx)

Code	Status	Description
`API_KEY_INVALID`	401	API key is malformed or doesn’t exist
`API_KEY_REVOKED`	401	API key has been revoked
`AUTH_TOKEN_MISSING`	401	No authentication provided
`AUTH_TOKEN_EXPIRED`	401	Session token has expired
`EMAIL_NOT_VERIFIED`	403	Email verification required for gateway access
`FORBIDDEN`	403	Insufficient permissions

Billing Errors

Code	Status	Description
`INSUFFICIENT_CREDITS`	402	Not enough credits for this call
`X402_PAYMENT_NEEDED`	402	Payment required to continue

Rate Limiting

Code	Status	Description
`GLOBAL_RATE_LIMIT_EXCEEDED`	429	Global user rate limit hit
`ENDPOINT_RATE_LIMIT_EXCEEDED`	429	Per-endpoint rate limit hit

Resource Errors

Code	Status	Description
`API_NOT_FOUND`	404	Requested connector doesn’t exist
`ENDPOINT_NOT_FOUND`	404	Endpoint path doesn’t exist on this connector
`USER_NOT_FOUND`	404	Referenced user not found
`PAYMENT_NOT_FOUND`	404	Referenced payment not found

Validation Errors

Code	Status	Description
`VALIDATION_ERROR`	422	Request body/params failed validation
`BAD_REQUEST`	400	Malformed request

Server Errors

Code	Status	Description
`UPSTREAM_ERROR`	502	Upstream API returned an error
`INTERNAL_ERROR`	500	Unexpected server error

Retry Logic

Credits are automatically refunded on upstream 5xx errors. Rate-limited requests (429) are rejected before credit deduction, so no credits are charged.

Safe to retry:

429 — Wait for retry-after seconds, then retry
502 — Upstream error, retry with exponential backoff
500 — Server error, retry with backoff (up to 3 attempts)

Do not retry:

400, 401, 403, 404, 422 — Fix the request first
402 — Add credits or upgrade your plan

Request IDs

Every response includes an x-request-id header. Include this ID when contacting support — it allows us to trace the full request lifecycle in our logs.

curl -v "https://api.openbits.ai/twitter/v1/users/by/username/elonmusk" \
  -H "X-API-Key: ob_live_YOUR_KEY" 2>&1 | grep x-request-id

Getting Started

Guides

AI Agents

CLI

Connectors

Error Handling

Error Handling

Response Format

Success

Error

Error Codes

Authentication Errors (4xx)

Billing Errors

Rate Limiting

Resource Errors

Validation Errors

Server Errors

Retry Logic

Request IDs

​Error Handling

​Response Format

​Success

​Error

​Error Codes

​Authentication Errors (4xx)

​Billing Errors

​Rate Limiting

​Resource Errors

​Validation Errors

​Server Errors

​Retry Logic

​Request IDs

Error Handling

Response Format

Success

Error

Error Codes

Authentication Errors (4xx)

Billing Errors

Rate Limiting

Resource Errors

Validation Errors

Server Errors

Retry Logic

Request IDs