Headers
Every request and response header of Noryo Merchant API, its value, and on which responses it is present.
HTTP header names are case-insensitive: the API writes them in lower case in its responses (noryo-request-id), the documentation writes them capitalised (Noryo-Request-Id). It is the same header.
Request headers
| Header | Routes | Required | Value |
|---|---|---|---|
Authorization | all | yes | Bearer nry_mer_<env>_<key_id>.<secret>. See Authentication. |
Content-Type | POST | yes | application/json. A parameter such as ; charset=utf-8 is accepted. Any other type returns 415. |
Idempotency-Key | POST /merchant/v1/enrichments | no, but see below | 1 to 255 bytes of visible ASCII (0x21 to 0x7E), with no normalisation. |
Idempotency-Key | POST …/refresh | yes | Same format. Its absence returns 400 identifier_required. |
Details:
- On create, the
Idempotency-Keyis optional provided the body carries anexternal_transaction_id; with neither, the request is refused with400 identifier_required. See The two identifiers. - An
Idempotency-Keyheader that is present but empty, too long, contains a space or a character outside visible ASCII, or is repeated, is refused with400 invalid_idempotency_key. Its shape is checked on every route, includingGET, where it has no effect. - A
Noryo-Request-Idsent by the client is ignored and replaced: you do not choose the Noryo identity of your request.
Response headers
| Header | Present on | Value |
|---|---|---|
Noryo-Request-Id | every response | req_<uuid>, the identifier of this attempt. Identical to the request_id in an error body. See Request IDs. |
Content-Type | every response | application/json for a success, application/problem+json for an error |
Cache-Control | every response | no-store |
Noryo-Idempotency-Replayed | 200 of both POST routes | true if the response comes from the idempotency memory, false otherwise |
Noryo-RateLimit-Limit | 200 of all three routes, and 429 | The burst capacity of your key's bucket |
Noryo-RateLimit-Remaining | 200 of all three routes, and 429 | The tokens left in your bucket |
Retry-After | 429, 503 busy, 503 pricing_not_activated | A whole number of seconds to wait |
Location | 200 of the refresh | The relative path of the new enrichment, for example /merchant/v1/enrichments/enr_dd424f15-… |
WWW-Authenticate | 401, 403 insufficient_scope | Bearer realm="noryo-merchant-api", error="invalid_token" or error="insufficient_scope" |
X-Content-Type-Options | every response | nosniff |
Referrer-Policy | every response | no-referrer |
X-Robots-Tag | every response | noindex, nofollow |
Error responses other than 429 do not carry the Noryo-RateLimit-* headers, even when they consumed a token. To follow your balance, read them on your 200 responses.
Location is relative
The refresh announces the new enrichment_id with a relative path, never an absolute URL: no hostname enters the contract. Resolve it against your configured base URL.
Retry-After is only set where retrying makes sense
A Retry-After only appears on refusals that a retry of the same request can clear: the rate limit, transient contention (busy), and billing not yet activated (pricing_not_activated). It never appears on a 400 or a 409. See Retries.
Published on 2026-10-09 10:18 UTC (version 2).