Errors

Error format

All errors return JSON:

{
  "error": "Description of what went wrong"
}

HTTP status codes

Status Code Meaning
400 Bad Request Missing or invalid parameters
401 Unauthorized Missing or invalid API key
403 Forbidden Valid key, but insufficient permissions
404 Not Found Provider, endpoint, or schema not found
429 Too Many Requests Rate limit exceeded (per-IP or per-key)
500 Internal Server Error Unexpected server error

Common errors

Invalid API key

Status: 401
{ "error": "Invalid API key" }

Fix: Check your API key is correct and starts with oac_live_.

Monthly limit exceeded (Free plan)

Status: 429
{
  "error": "Rate limit exceeded",
  "limit": 100,
  "remaining": 0,
  "reset_at": 1719792000
}

Fix: Wait for monthly reset or upgrade to Pro.

IP rate limit exceeded

Status: 429
{ "error": "Rate limit exceeded" }

Headers include Retry-After (seconds to wait).

Fix: Slow down request rate. Default is 120 requests/minute per IP.

Provider not found

Status: 404
{ "error": "Couldn't find ApiProvider" }

Fix: Check the provider slug. Use /api/v1/providers/search?q=name to find the correct slug.

Endpoint not found

Status: 404
{ "error": "Couldn't find Endpoint" }

Fix: Verify method and path match exactly. Use /api/v1/providers/:slug/endpoints to list available endpoints.

Spec not available

Status: 404
{ "error": "No spec version for <slug>" }

Fix: The provider exists but has no ingested spec. You can submit it via POST /api/v1/resolve.

Getting help