Reference

Errors

The error format, HTTP status codes, every error code and how to quote a request ID to support.

Every error uses the same JSON shape, and the HTTP status tells you the class of problem.

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "The request was invalid.",
    "request_id": "req_01example0000000000000000",
    "details": { "email": ["The email field must be a valid email address."] },
    "doc_url": "https://example.com/developers/errors#validation_failed"
  }
}

Field	Meaning
`type`	The broad category, for example `authentication_error`, `permission_denied`, `validation_error`, `not_found`, `business_conflict`, `idempotency_error`, `rate_limited`, `server_error`.
`code`	A stable machine-readable code. Branch on this, not on `message`, whose wording may improve.
`message`	A human-readable explanation.
`request_id`	The identifier of this request.
`details`	Optional. For validation errors, a map of field name to messages.
`doc_url`	A link to the entry for this code on this page.

Error responses are never cached, and never contain stack traces, file paths, SQL or internal identifiers.

Request ID and support

Every response, successful or not, carries an X-Request-Id header, and errors repeat it as error.request_id. It is always generated by NEXTOREx. When you contact support, include the request ID, the time, the endpoint and your key prefix (never the secret). That lets us find the exact request.

Status codes

Status	Meaning
`400`	The request could not be processed (for example malformed JSON).
`401`	The key is missing, malformed, unknown, revoked, expired or for another environment.
`403`	The key is genuine but not allowed: scope, role permission, purchased plan or Developer API access.
`404`	The record does not exist or is outside what your key may see. These are deliberately indistinguishable.
`405`	The method is not available on that endpoint.
`409`	A business or idempotency conflict.
`422`	The request is understood but invalid.
`429`	Rate limited. Wait for `Retry-After`.
`5xx`	A server-side problem. The message is generic and safe. Writes are rolled back, so retrying is safe with the same `Idempotency-Key`.

Authentication errors (401)

invalid_api_key

The key is missing or does not match any active key. An unknown key and a wrong secret look identical on purpose.

malformed_api_key

The value is not shaped like a NEXTOREx key. Check you sent the whole key, with no extra spaces or quotes, as Authorization: Bearer <key>.

api_key_revoked

The key was revoked. Create a new key.

api_key_expired

The key passed its expiry date. Create or rotate a key.

api_key_environment_mismatch

You used a test key against a live deployment or the other way round.

api_key_context_invalid

The company, place in the hierarchy or role the key was issued for is no longer valid. Ask an administrator to issue a new key.

Permission errors (403)

insufficient_scope

The key does not have the scope the endpoint needs. The response details name the required scope.

insufficient_permission

The key's role does not allow this operation, even though the scope is present. Ask an administrator to adjust the role, or use a key with a suitable role.

plan_not_entitled

Your subscription does not include what this endpoint needs, for example the application that owns it.

developer_api_not_entitled

Developer API access is not enabled for your account. Existing keys resume working as soon as it is restored.

forbidden

A general refusal, for example an application that is not active for your account.

api_context_invalid

The request context could not be established safely. Contact support with the request ID.

Not found (404)

resource_not_found

No such record within your key's reach. It may not exist, may belong to someone else, or may sit outside your part of the hierarchy.

Request errors

bad_request

The request could not be processed, for example because the body was not valid JSON.

method_not_allowed

That HTTP method is not allowed on this endpoint.

Conflicts (409)

duplicate_lead

A lead with the same email or phone already exists in your key's part of the hierarchy.

lead_locked

The lead is locked by its business flow and cannot be edited.

invoice_not_payable

The invoice is not in a state that can be paid online, or nothing is due.

payment_not_available

No online payment option is enabled for this invoice.

idempotency_key_reused

The Idempotency-Key was already used with a different request. Use a new key. See Idempotency.

idempotency_request_in_progress

A request with this key is still being processed. Wait for Retry-After seconds and retry.

Validation errors (422)

validation_failed

A field or query parameter is invalid, unknown or not permitted. details lists each offending name. Unknown fields are never ignored.

reserved_context_field

The request contained a tenant, company, hierarchy or role identifier (or an X-Tenant-Id style header). These are fixed by the key and cannot be supplied.

idempotency_key_required

A POST was sent without an Idempotency-Key header.

idempotency_key_invalid

The Idempotency-Key is not 8 to 128 characters of letters, digits and . _ : -.

resource_limit_reached

Your plan's limit for this resource, for example active students, is used up. Nothing was written. details shows the limit and current use.

Rate limiting (429)

rate_limit_exceeded

Too many requests. Wait for the number of seconds in Retry-After. See Rate limits.

Server errors (5xx)

internal_error

An unexpected error. The message is intentionally generic. Retry with the same Idempotency-Key; if it persists, contact support with the request_id.