Errors

Error responses use a consistent JSON envelope. Per-endpoint status codes and response schemas are listed in the API reference.

Error envelope

All errors return a single top-level error object with:

Field Description
type High-level category (e.g. invalid_request_error, authentication_error, api_error)
code Machine-readable code for programmatic handling
message Human-readable summary
details Optional array of field-level errors

Each details entry may include param, code, and message.

Optional fields requestId and docUrl are reserved for future use.

The API reference documents the ErrorResponse schema and which status codes each endpoint can return.

Design notes

Uniform 404s — The API returns the same 404 shape whether a resource does not exist or is not accessible with your key. This is intentional and avoids leaking cross-brand information.

Validation errors — 422 responses include a details array. Check it for field-specific messages (e.g. an invalid pagination cursor or out-of-range query parameter).

Non-confirming 409s — Returned by employee creation (POST /employees): the request conflicts with existing state and nothing was created. Two create fields can conflict: email (identifies a person across Nory, not within one brand) and, when supplied, externalReference (unique within your brand). The response deliberately does not say which field or where the conflict is, and a 409 is not evidence that the person exists in your brand. Read it as "use a different value", and do not retry unchanged. Omitting externalReference means Nory cannot de-dupe on your id — two creates with different emails can both succeed.

Retry guidance

Situation Retry?
Authentication failure (401) No. Fix your API key
Permission failure (403) No. Your key lacks write access, or the brand's data agreement with your integration does not cover a field you sent (each one is listed in details)
Not found (404) No. Check IDs and filter values
Validation failure (422) No. Fix parameters; restart pagination if the cursor is invalid
Conflict (409) No. Nothing was created; retrying unchanged returns the same conflict
Server or upstream failure (5xx) Yes. Retry GET requests with exponential backoff

GET requests are idempotent, so they are always safe to retry.

Employee creation (POST /employees) is not idempotent by default. Send an Idempotency-Key header to make a retry safe: resending the same key and body returns the employee created the first time (200 with Idempotent-Replayed: true) rather than creating a second one. Creating an employee requires a write-enabled API key — keys are read-only by default, and a read-only key returns 403.