Errors
Every error is an RFC 7807 body, sent with Content-Type: application/problem+json:
{
"type": "https://errors.narya.dev/problems/validation",
"title": "Request validation failed",
"status": 400,
"detail": "name is required",
"instance": "/integration/v1/companies",
"request_id": "0192f6c4-9b31-7e42-a5d6-e7f8a9b0c1d2",
"invalid_params": [
{"name": "name", "code": "required", "reason": "name is required"}
]
}Quote the request_id when you report a problem to Narya.
Field errors
On a 400, and on a 409 caused by a field, such as an external_ref already in use, invalid_params has one entry per field:
nameis the field.codeis why it was refused, such asrequired,too_long,malformed,not_found,already_taken,immutableorexclusive.reasonis a note for debugging. Do not parse it or show it to end users.
Act on code. New codes can be added, so treat one you do not recognise as a generic error on that field.
Status codes
| Status | Meaning | What to do |
|---|---|---|
400 | A parameter or the body failed validation. | Fix the fields named in invalid_params. |
401 | The key is missing, malformed, unknown, revoked or expired. | Check the key. Ask your Narya contact for a new one if it was revoked. |
403 | The key's role does not allow this action, or the action needs a key for your whole organisation. | Ask your Narya contact for a key that allows it. See Authentication. |
404 | The record does not exist, or is outside your key's reach. | Check the id, and the key's reach. |
409 | The request conflicts with the record's current state. | Read detail, and invalid_params if present. A retry with no change gets the same result, unless detail says to retry. |
413 | The body is over 1 MiB. | Send a smaller body, or fewer serials in a batch. |
429 | Too many requests from this key. | Wait for Retry-After seconds, then retry. See Rate limits. |
500 | Narya failed. | Retry with backoff. Report it with the request_id if it persists. |
503 | Activation codes are briefly unavailable. | Wait for Retry-After seconds, then retry. |