Errors & status codes

Standard error format

All errors return a JSON body:

{
  "error": "string",
  "message": "Human-readable description"
}

Code	Name	When it occurs
`200`	OK	Request succeeded
`400`	Bad Request	Missing or invalid parameters
`401`	Unauthorized	API key missing, invalid, or revoked
`403`	Forbidden	Your plan doesn’t include this feature
`404`	Not Found	Resource doesn’t exist or doesn’t belong to your account
`429`	Too Many Requests	Rate limit exceeded — back off and retry
`500`	Internal Server Error	Something went wrong on NearIQ’s side

When you exceed the rate limit, the response includes headers telling you when to retry:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

Implement exponential backoff: wait Retry-After seconds, then retry. Don’t hammer the API — repeated 429s may result in temporary key suspension.

{
  "error": "Forbidden",
  "message": "API access requires a Growth plan or higher.",
  "planRequired": "growth"
}