Errors

Every error is a problem details document, application/problem+json. Its type links to the code’s entry on this page:

{
  "type": "https://developers.dnerohq.com/guides/errors/#key_revoked",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key has been switched off or has expired.",
  "code": "key_revoked"
}

Branch on code. It is stable: a code is never renamed or reused. title and detail are written for people and may be reworded at any time.

An invalid request also lists what was wrong in errors, each with where the problem is and why:

{
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "invalid_request",
  "detail": "validation failed",
  "errors": [{ "location": "query.limit", "message": "expected number <= 200", "value": 500 }]
}

Retrying

Status	Retry?
4xx	No, except 429. The same request will fail the same way.
429	Yes, after the Retry-After header’s seconds.
502, 503, 504	Yes, with backoff.
500	Once or twice, with backoff. If it persists, contact Dnero support with the X-Request-Id response header.

Codes

Your key

The key itself: not sent, not readable, or no longer good.

missing_key

401 No API key was sent.

What to do: send it as Authorization: Bearer <key>.

invalid_key

401 What was sent is not a Dnero API key.

What to do: check it was copied whole, with nothing added at either end.

key_expired

401 The key had an expiry date, and it has passed.

What to do: ask the organisation’s admin for a new key.

unauthorised

401 The request needs an API key and did not have a usable one.

What to do: send a key as Authorization: Bearer <key>.

key_revoked

403 The key was revoked or switched off in the Dnero portal.

What to do: ask the organisation’s admin whether it should still work. If it should, they make a new one.

assistant_key

403 The key is an assistant key: it was made for the Dnero assistant, not for the API.

What to do: ask the organisation’s admin for an API key, which they make under Automation > Access > API keys. The two kinds are made in different places, and the assistant’s will never work here.

key_without_access

403 The key exists but has no access set up in Dnero.

What to do: contact Dnero support.

key_without_organisation

403 The key does not belong to an organisation.

What to do: contact Dnero support.

organisation_not_linked

403 The key’s organisation is not linked to Dnero.

What to do: contact Dnero support.

key_wrong_organisation

403 The key’s access belongs to a different organisation.

What to do: contact Dnero support.

What the key reaches

The key is good, but this is outside what it was given.

public_api_not_enabled

403 The API is not switched on for the key’s organisation.

What to do: the organisation asks Dnero to switch it on.

key_without_sites

403 The key reaches no site.

What to do: the admin gives it a site under Automation > Access > API keys.

insufficient_access

403 The key reaches the site, but not with the access this needs: reading where it has none, or writing where it may only read.

What to do: the admin changes its access under Automation > Access > API keys. GET /v1/me says what it has now.

forbidden

403 The key may not do this.

What to do: check what the key reaches with GET /v1/me.

site_not_found

404 The key does not reach that site, or there is no such site.

What to do: use a siteId from GET /v1/sites, which lists only the sites the key reaches.

The request

Something in the request itself. The same request will fail the same way.

bad_request

400 The request could not be read, for example malformed JSON.

What to do: check the body is valid JSON.

invalid_request

422 The request was read but is not valid.

What to do: errors says which fields are wrong and why.

not_found

404 There is no such endpoint, or no such record that this key can reach.

What to do: check the path, and that the code belongs to this site.

not_a_modifier_group

422 The code given to a modifier group endpoint is a product of another type.

What to do: use the product endpoints for it, or pass a modifier group’s code.

invalid_cursor

400 The cursor is not one this API gave out.

What to do: pass nextCursor from the previous page unchanged.

idempotency_key_required

400 A POST was sent without an Idempotency-Key header.

What to do: send a new unique key with each thing you create. See idempotency.

idempotency_key_reused

409 This Idempotency-Key was already used for a different request.

What to do: use a new key for each thing you create.

request_in_progress

409 The first request with this Idempotency-Key is still being handled.

What to do: wait a moment and retry with the same key.

method_not_allowed

405 The endpoint exists but does not take that method.

What to do: check the method against the reference.

not_acceptable

406 The response cannot be sent in a format the Accept header allows.

What to do: accept application/json.

request_too_large

413 The request body is larger than the API accepts.

What to do: send fewer records at once.

unsupported_media_type

415 The request body is not JSON.

What to do: send Content-Type: application/json.

Rate and us

Too many requests, or something on Dnero’s side. These are worth retrying.

rate_limited

429 The key has used its requests for this minute.

What to do: wait the Retry-After header’s seconds. See rate limits.

images_unavailable

503 Pictures cannot be stored at the moment. Everything else works.

What to do: try the picture again later.

upstream_unavailable

502 Something Dnero depends on did not answer in time.

What to do: retry with backoff.

server_error

500 Something went wrong on Dnero’s side. It has been logged.

What to do: retry once or twice. If it persists, contact Dnero support with the X-Request-Id response header.