Skip to main content
When a request fails, the API returns a non-2xx HTTP status and a consistent error envelope. Read the HTTP status for the category and the error.code for the specific, stable reason.

​
Error envelope

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API-key management requires admin role.",
    "details": { "...": "..." }
  },
  "meta": { "request_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" }
}
FieldDescription
error.codeStable, machine-readable code — branch on this, not on the message.
error.messageHuman-readable explanation, safe to surface in logs.
error.detailsOptional object with extra context (e.g. which field failed validation).
meta.request_idUnique id for this request. Quote it when contacting support.

​
Status codes

StatusMeaningWhat to do
400 Bad RequestMalformed request or invalid parameters.Fix the request shape or values.
401 UnauthorizedMissing, malformed, expired, or revoked credential.Check the Authorization header and your API key.
403 ForbiddenAuthenticated, but the key lacks access to this resource or action.Confirm the action is allowed for your tenant.
404 Not FoundThe resource doesn’t exist, or isn’t yours.Check the id; the API never reveals other tenants’ resources.
409 ConflictThe request conflicts with current state.Re-read the resource and retry.
422 UnprocessableThe request was well-formed but semantically invalid.See error.details for the offending field.
429 Too Many RequestsYou’ve hit the rate limit.Back off and retry after Retry-After.
5xx Server ErrorSomething went wrong on Neo’s side.Retry with backoff; if it persists, contact support with the request_id.
Treat any 4xx as a bug in the request to fix, not to retry blindly — except 429, which you should retry after the Retry-After delay. Retry 5xx with exponential backoff.

​
What’s next

Rate limits

How much you can call, and how to stay under the limit.