Skip to content
Last updated

Errors

The Dentally NexGen API uses Problem Details for HTTP APIs (RFC 7807) for every error response. This means error bodies are predictable: same shape, same fields, machine‑readable.

Envelope

{
  "type": "https://httpstatuses.io/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "Missing required field 'address'",
  "instance": "/v2/sites",
  "traceId": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00"
}
FieldTypeNotes
typeURIIdentifies the problem type. Defaults to about:blank if absent.
titlestringShort, human‑readable summary. Stable for a given problem type.
statusintegerHTTP status code mirrored in the body.
detailstringHuman‑readable explanation specific to this occurrence.
instanceURIReference to the specific occurrence (typically the request path).
traceIdstringDistributed trace identifier — quote this when contacting support.

The envelope is open to additional properties: future problem types may add fields. Clients should ignore unknown properties.

Standard responses

StatusWhenNotes
400 Bad RequestValidation failed, malformed request, or unknown Dentally-API-Version.detail describes the offending field or header.
401 UnauthorizedMissing, invalid or expired bearer token.See Authentication.
404 Not FoundThe resource does not exist or is not visible to the caller's practice scope.
410 GoneThe requested API version has been sunset.Includes Link rel="sunset" to the changelog.
429 Too Many RequestsA rate limit or spike arrest was exceeded.Includes RateLimit-* response headers. See Rate limiting.
4XX otherOther client errors (conflict, etc.).Same Problem Details envelope.
5XXServer error.detail is intentionally generic. Use traceId when reporting.

Handling guidance

  • Branch on status, not on title or detail strings — those may be refined or localised.
  • Log traceId with your application logs so support can correlate failures end‑to‑end.
  • Treat 4XX other and 5XX as the catch‑all for status codes not individually documented on an operation.

For per‑operation responses, see the API reference.

Rate limiting

Conventions