Errors - Neo Agent

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" }
}

Field	Description
`error.code`	Stable, machine-readable code — branch on this, not on the message.
`error.message`	Human-readable explanation, safe to surface in logs.
`error.details`	Optional object with extra context (e.g. which field failed validation).
`meta.request_id`	Unique id for this request. Quote it when contacting support.

Status codes

Status	Meaning	What to do
`400` Bad Request	Malformed request or invalid parameters.	Fix the request shape or values.
`401` Unauthorized	Missing, malformed, expired, or revoked credential.	Check the `Authorization` header and your API key.
`403` Forbidden	Authenticated, but the key lacks access to this resource or action.	Confirm the action is allowed for your tenant.
`404` Not Found	The resource doesn’t exist, or isn’t yours.	Check the id; the API never reveals other tenants’ resources.
`409` Conflict	The request conflicts with current state.	Re-read the resource and retry.
`422` Unprocessable	The request was well-formed but semantically invalid.	See `error.details` for the offending field.
`429` Too Many Requests	You’ve hit the rate limit.	Back off and retry after `Retry-After`.
`5xx` Server Error	Something 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.

⌘I