Errors – status codes and error codes of the REST API¶
This page lists every HTTP status and error code a caller of the REST API can receive, what causes it and what to do. It is intended for the people who build and operate the calling system.
1. At a glance¶
The REST API answers errors in four forms:
| Form | Where | Recognised by |
|---|---|---|
| API error | Records and actions (/api/v1/...) |
JSON with error and errorDescription |
| OAuth error | Token endpoint (/api/oauth/token) |
JSON with error and error_description |
| License error | Every API address while the installation has no valid license | Status 503, JSON with error = license_invalid and error_description |
| Without nexxcite error code | Missing token, wrong address, invalid JSON | Empty body, or a validation report (section 4) |
Rule for the calling system: decide by the HTTP status and the error code. The codes
are stable; the texts in errorDescription and error_description explain the case for people and
can change.
2. API errors (records and actions)¶
{
"error": "record_not_found",
"errorDescription": "Record '9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58' of entity 'Customer' does not exist or is not accessible.",
"validationErrors": null,
"requiredFields": null
}
| Property | Meaning |
|---|---|
error |
The error code (table below) |
errorDescription |
Explanation for people |
validationErrors |
Only for record_not_saved: fields still marked as invalid – fieldDefId, field (technical name), value (the rejected value as text). Otherwise null. |
requiredFields |
Only for record_not_saved: per record, the required fields without a value – entityDefId, entityRecId, relationshipId (set when the record is a related record), fields with fieldDefId and field. Otherwise null. |
400 Bad Request – the request is wrong¶
error |
Cause | Operations |
|---|---|---|
field_missing |
A field name is empty; a full text clause without fields | Records, queries |
field_not_found |
No field of the entity matches the name | Records, queries |
field_ambiguous |
Several fields have this display name – use the technical name | Records, queries |
field_without_type |
The field has no field type and cannot be written | Create, update |
invalid_field_value |
The value does not fit the field type; in/notIn without a JSON array; empty text for a non-text field |
Records, queries |
invalid_operator |
Unknown or missing operator in a clause | Queries |
invalid_gate |
gate is not and or or |
Queries |
invalid_sort_direction |
dir is not asc or desc |
Queries |
invalid_date_part |
Unknown datePart |
Queries |
invalid_date_part_unit |
Unknown or missing unit for is / isNot |
Queries |
relationship_missing |
A related clause without relationshipDefId |
Queries |
relationship_not_found |
The relationship does not exist; when reading a record, also if it does not belong to the entity | Read, queries |
relationship_invalid |
The relationship has no related entity, or that entity does not exist | Queries |
value_missing |
A full text clause without value |
Queries |
unknown_clause_type |
A clause of an unsupported kind | Queries |
invalid_target |
target without entityDefId or entityRecId |
Run action |
variable_not_found |
A key in params is not a variable of the action |
Run action |
action_without_variables |
params cannot be applied to this action |
Run action |
The errorDescription of the invalid_… codes lists the allowed values.
401, 403, 404, 422, 500¶
| HTTP status | error |
Cause | What to do |
|---|---|---|---|
| 401 | – (empty body) | No token, token expired or revoked, user locked | Request a new token (section 5) |
| 401 | unauthorized |
The user of the token could not be determined when queuing a background action | Request a new token |
| 403 | forbidden |
The "Add Limits" or "Edit Limits" of the API user do not admit the change | Check the roles of the API user |
| 404 | entity_not_found |
No entity with this ID | Check the ID |
| 404 | record_not_found |
No record with this ID, or the record is outside the "Read Limits" of the API user | Check the ID and the read limits |
| 404 | action_not_found |
No action with this ID | Check the ID |
| 422 | record_not_saved |
Required fields missing, a field invalid, or a rule that runs before saving reported an error | See requiredFields, validationErrors and errorDescription |
| 500 | query_failed |
The database could not run a query. The answer does not say why; the reason is in the application log. | Check the request; if it persists, the operator checks the application log |
| 500 | server_error |
Unexpected error ("The request could not be processed.") | The operator checks the application log |
404 deliberately does not distinguish "does not exist" from "not readable", so that the API does
not reveal records the user may not see.
3. Errors of the token endpoint¶
| HTTP status | error |
Cause |
|---|---|---|
| 400 | unsupported_grant_type |
grant_type missing or not client_credentials |
| 400 | invalid_request |
Client ID or client secret missing |
| 400 | temporarily_unavailable |
All licenses are in use – try again later |
| 401 | invalid_client |
Unknown client ID, wrong or expired secret, no user assigned, user locked or deleted |
| 415 | – | The body is not application/x-www-form-urlencoded |
| 500 | server_error |
No valid signing key configured – the REST API sign-in is off |
Details: Authentication.
4. Answers without a nexxcite error code¶
Some requests are rejected before nexxcite processes them. They do not carry the error property
described above.
| HTTP status | Cause | Body |
|---|---|---|
| 400 | The body is not valid JSON; a property has the wrong JSON type (for example text for waitForCompletion); a query clause without type, with an unknown type, or with type not as its first property |
Validation report (below) |
| 401 | No valid token | Empty; header WWW-Authenticate: Bearer … |
| 404 | Unknown address, or an ID in the path that is not a valid ID | Empty |
| 405 | Known address, wrong method (for example PUT or DELETE) |
Empty |
| 415 | Content-Type is not application/json (records and actions) |
Validation report |
A validation report has this form (standard format "problem details", RFC 9457):
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"$.fields[0].value": [ "'}' is an invalid start of a value. Path: $.fields[0].value | LineNumber: 0 | BytePositionInLine: 41." ]
},
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}
errors names the position in the JSON ($.fields[0].value, $.query and so on). The texts are technical and can change
between versions.
5. License error – 503¶
{
"error": "license_invalid",
"error_description": "This installation has no valid license."
}
While the installation has no valid license – none entered, damaged or expired – every request to the
API and the token endpoint is answered with 503. This is not a temporary overload: an administrator
has to enter a valid license key (see Licensing).
temporarily_unavailable from the token endpoint is different: the license is valid, but all
licenses are in use at the moment.
6. Recommended handling¶
| Status | Retry? | Action of the calling system |
|---|---|---|
| 400, 404, 405, 415 | No | Fix the request; log error and errorDescription |
| 401 | Once | Request a new token, repeat the call once. If it fails again: check the API access. |
| 403 | No | The API user lacks the right – an administrator checks its roles |
| 422 | No | Fix the data (requiredFields, validationErrors) |
400 temporarily_unavailable (token) |
Yes, later | Wait and retry, for example after 30 seconds and then with growing intervals |
| 500 | With care | Retry later. For create and run action, check first whether the first attempt took effect – a retry can create a second record or run the action twice. |
503 license_invalid |
No | Inform the administrator |