Validation
The request schema is closed: every validation refusal, its code, its exact message, and the rules that most often surprise (upper case, null, UTC, unknown fields).
A request body is validated against a closed schema: an unknown field is never ignored, it makes the request fail. This strictness makes the comparison of two requests total: a field silently tolerated would make two requests differ that are identical in the engine's eyes, and would produce an unjustified 409.
Every body validation error returns 400 with the code invalid_request. The detail field says which rule failed; the first failing rule stops validation.
{
"type": "https://developer.noryo.app/errors/invalid_request",
"title": "Invalid request",
"status": 400,
"code": "invalid_request",
"detail": "currency must be an ISO 4217 code",
"request_id": "req_…"
}Build your logic on code, not on detail. The detail text is written for a human, in English, and may be reworded without a version change.
The detail messages
detail | Cause |
|---|---|
body must be a JSON object | The body is an array, a string, a number or null |
unknown field: <name> | A field outside the schema is present |
descriptor is required | descriptor missing, empty, whitespace only, or not a string |
descriptor is too long | More than 512 characters |
amount must be a finite number | amount is not a JSON number (a string "12.40", null) |
currency must be an ISO 4217 code | Not exactly three upper-case letters (eur, EURO, null) |
occurred_at must be ISO 8601 UTC | Not a string shaped YYYY-MM-DDTHH:MM:SS followed by an optional fraction and Z, or a date that does not exist |
country must be ISO 3166-1 alpha-2 | Not exactly two upper-case letters |
mcc must be four digits | Not a string of exactly four digits (a number such as 5814 included) |
external_transaction_id must be 1..255 characters | Empty, too long, or not a string |
The rules that surprise
Unknown fields are refused. A typo (occured_at) or a field from your internal model sent by mistake returns unknown field: occured_at. Some names are reserved for the server and refused the same way if they appear in the body: status, confidence, billable, units, environment, source, customized, enrichment_id, request_id, among others. The client can never declare what the server computes.
null is not an absence. For an optional field you do not have, omit the key. "amount": null is refused.
Upper case is required. currency and country are compared verbatim; the validator refuses eur rather than correcting it. See Formats.
occurred_at must be in UTC, with Z. 2026-09-06T13:42:00+02:00 is refused: convert it to 2026-09-06T11:42:00Z. A well-shaped date that does not exist (2026-02-30T10:00:00Z, an hour of 24, a second of 60) is refused the same way, with 400.
mcc is a string. Send "5814", not 5814: a numeric 5814 is refused with 400 and mcc must be four digits.
The body of a refresh
The body of POST …/refresh accepts the six economic fields and nothing else. An external_transaction_id is refused there (unknown field: external_transaction_id): the refresh targets the enrichment named in the URL, and accepting a second identifier would let one request designate two transactions. See Refresh.
Refusals that come before body validation
| Code | Status | Cause |
|---|---|---|
unsupported_media_type | 415 | Content-Type missing or other than application/json |
request_entity_too_large | 413 | Body over 16 KiB |
invalid_json | 400 | Body that is not valid JSON, or an empty body |
invalid_idempotency_key | 400 | Malformed Idempotency-Key header |
Other route-specific refusals
| Code | Status | Cause |
|---|---|---|
insufficient_scope | 403 | The key lacks enrich:write |
identifier_required | 400 | Create call with neither Idempotency-Key nor external_transaction_id, or refresh without Idempotency-Key |
On create, the order is: body, scope, identifier. On refresh: path identifier, Idempotency-Key, scope, then body. The complete order of checks is described in Requests.
Published on 2026-10-09 10:18 UTC (version 2).