Every code the seller door refuses with, its HTTP status and what it means.
A refusal is a JSON object {"code", "sentence", "correlationId"}. The code is one of the 47 below and is stable. The sentence is for people and may be reworded. The correlationId names the call in the door's log.
Every 503 answer carries Retry-After: 1: retry the same request after a second. Every other refusal is final for the request as sent.
The same codes are exported as REFUSALS from @integraledger/agentic-connectors, each with its status.
The body is not the operation's JSON object.
| Code | Meaning |
|---|
door/malformed | The body is not the operation's JSON object: it is not JSON, it is not an object, or a member is missing, has the wrong type, or is not in the schema. |
No valid seller credential.
| Code | Meaning |
|---|
door/unauthenticated | The request carries no seller credential, or one the door does not know. The answer carries WWW-Authenticate: Bearer realm="seller-door". |
The request carries an Origin header; the door serves servers only.
| Code | Meaning |
|---|
door/browser-origin | The request carries an Origin header. The door serves servers only; call it from your backend. |
Nothing known by that name for this tenant.
| Code | Meaning |
|---|
door/not-found | Nothing is known by that name for this tenant: no such path, or no record with that ATR hash. |
door/resource-unknown | The resource names no resource declared for this tenant. |
claim/unknown | No record matches the hash the payment carries. |
| Code | Meaning |
|---|
door/method | The path is served, but not with this method. |
The record is in a state that does not allow this.
| Code | Meaning |
|---|
issue/mint-request-reused | This mintRequestId was issued for different offers, content or request. A changed checkout needs a new id. |
issue/mint-request-lapsed | This mintRequestId's record has lapsed. Append :<n> with a new n and issue again. |
claim/in-progress | This ATR's payment is already claimed. On a retry of the same presentation, the first attempt won. |
claim/paid | This ATR is already paid. |
claim/not-this-request | The payment is not for the options and request this ATR was issued for. |
claim/channel-open | This channel is already open under an ATR. Serve its later requests yourself, and never claim them. |
claim/channel-not-open | No opening of this channel was claimed. Claim the opening first. |
claim/agreement-first | The record needs the agreement step, and the agreement payment is not recorded yet. Claim this payment once it is. |
claim/instrument-claimed | This payment instrument is already claimed for another record. |
report/pairing-mismatch | The report names a pairing other than the record's. |
settle/other-reference | This record was settled with another reference. |
settle/not-settling | The record is not in a state that allows this report. |
The challenge has lapsed.
| Code | Meaning |
|---|
claim/lapsed | The challenge for this ATR has lapsed. |
The body is larger than this operation accepts.
| Code | Meaning |
|---|
door/too-large | The body is larger than the operation accepts. |
The body is not application/json.
| Code | Meaning |
|---|
door/media-type | The body is not sent as application/json. |
The request cannot be served as sent.
| Code | Meaning |
|---|
door/request-required | The offer or claim is on an x402 surface and carries no request commitment. |
door/chosen-required | The report is for a record with no claim, and needs chosen: the option the payment paid, as issued. |
door/reference-required | The report needs a reference of 1 to 256 characters with no control characters. |
door/receipt-required | The paid report is for a confirm-only channel pairing, and needs the receipt its opening answered. |
issue/input-bounds | The request is outside the bounds the door accepts (for example more than 16 offers or 56 content slots). |
issue/pairing-not-served | An offer names a pairing the resource is not declared to serve. |
issue/offer-refused | An offer's pairing cannot place the hash in that option. The sentence names the pairing and its own code. |
issue/mixed-protocols | The offers name pairings of more than one protocol. One issue serves one protocol. |
core/slot-name | A content slot's name is not allowed: it must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$. |
core/slot-reserved | A content slot uses a name the ATR reserves (atrVersion, id, or the binding's slot). |
core/slot-duplicate | Two content slots have the same name. |
core/content-not-json | A content slot's bytes are not exactly one JSON value (RFC 8259). |
core/binding-not-json | An offer cannot be recorded as JSON. |
core/too-large | The ATR would be larger than the size the door allows. |
claim/pairing-unknown | The pairing is not one this payment or the chosen option offers. |
claim/not-bound | The payment carries no ATR hash the door can read in the pairing's field. |
claim/nothing-to-check | The pairing carries nothing the buyer signs. Report the payment instead. |
Not available now; retry after one second.
| Code | Meaning |
|---|
issue/deadline | The ATR was not ready in time. Retry with the same mintRequestId. |
issue/contributor-unavailable | A contributor the seller configured did not answer. Retry shortly. |
issue/storage-unavailable | The ATR could not be written to the seller's storage, so no challenge may go out. Retry shortly. |
issue/store-unavailable | The record store is not available. Retry shortly. |
issue/capacity | The record store is at capacity. Retry shortly. |
claim/store-unavailable | The record store is not available. Retry shortly. |
claim/read-unavailable | The landed payment could not be read on the rail yet. Retry shortly. |
settle/store-unavailable | The record store is not available. Retry shortly. |