Error protocol

Function availability

Available

The function described exists and is tested; the page also states what it does not do.

Format of API error responses (RFC 9457), stable codes, categories and HTTP statuses, correlation identifier and confidentiality rules.

Every NEXCLARA API error is returned in the RFC 9457 "Problem Details" format, with the application/problem+json content type. The format is the same for every operation. It carries a stable code: the code, not the text, is the contract.

The body of an error response

Synthetic example: no real data

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "LINK_IDEMPOTENCY_KEY_REUSED",
  "category": "conflict",
  "correlation_id": "c0ffee00-0000-4000-8000-000000000000",
  "retryable": false,
  "context": {}
}

Field	Meaning
`type`, `title`	standard RFC 9457 fields; `title` is the HTTP phrase, short and not translated
`status`	HTTP status of the response
`code`	stable error code, in capitals; it is also the interface's translation key
`category`	nature of the error (see below)
`correlation_id`	identifier of the exchange, identical to the response's `X-Request-ID` header
`retryable`	true when retrying the same request makes sense
`context`	safe details: never a secret, never personal data

Categories and HTTP statuses

The translation of a category into an HTTP status is done in a single place of the platform, and it is fixed:

Category	Status	When
`validation`	422	input refused; the response lets the client correct it
`not_found`	404	resource that does not exist within the authorised scope
`conflict`	409	state incompatible with the requested operation
`authentication`	401	identity not established: token missing, invalid, expired
`permission`	403	identity established, insufficient right
`configuration`	500	deployment configuration defect
`dependency`	503	dependency unavailable (database, for example)
`integrity`	409	integrity check failed
`internal`	500	unexpected defect; no detail is disclosed

The only exception: a request refused before it reaches an operation (an unsupported HTTP method, for example) keeps the HTTP status of that refusal, with the code HTTP_ERROR; an unknown address returns NOT_FOUND.

Confidentiality rules

no raw technical message (stack trace, SQL error) leaves the platform: an unexpected defect returns INTERNAL_ERROR, without detail, and the correlation identifier allows investigation;
for a validation error, only the location of invalid fields is given, never their value, which may be personal data;
a resource of another institution responds exactly like a resource that does not exist, and a permission refusal does not reveal the target object;
a failed sign-in returns the same response, whatever the cause.

Good practice on the client side

handle errors by their code, never by their title;
retry only if retryable is true, with an increasing delay;
keep correlation_id in the calling system's logs, so it can be given to support.

The operation did not complete box, with the cause and the line Identifier to quote to support followed by an identifier. — An error displayed with the correlation identifier to quote to support. Excerpt, local environment. Interface shown in French; the application is also available in English. Screenshot of the real product, synthetic data.

Known limitation of the contract

The OpenAPI contract still describes 422 responses with the application framework's generic schema, and does not list the possible error codes of each operation. The actual response nevertheless follows the format described here. Renaming a code would break the contract: existing codes do not change within the same API version.

About this page

Editorial status: Approved
Written by: Équipe produit NEXCLARA
Reviewed by: claude-relecteur-independant
Approved on: October 16, 2026
Revision: 2
Updated: October 15, 2026
Classification: Public