# Refusal codes

> Every code the seller door refuses with, its HTTP status and what it means.

Source: https://connectors.integraledger.com/reference/refusals

<!-- Generated by scripts/docs.mjs from contract/openapi.json and scripts/refusal-meanings.json. Edit the source, then run: node scripts/docs.mjs -->

# Refusal codes

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.

## 400

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. |

## 401

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"`. |

## 403

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. |

## 404

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.                                               |

## 405

| Code          | Meaning                                       |
| ------------- | --------------------------------------------- |
| `door/method` | The path is served, but not with this method. |

## 409

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.                                                              |

## 410

The challenge has lapsed.

| Code           | Meaning                                |
| -------------- | -------------------------------------- |
| `claim/lapsed` | The challenge for this ATR has lapsed. |

## 413

The body is larger than this operation accepts.

| Code             | Meaning                                        |
| ---------------- | ---------------------------------------------- |
| `door/too-large` | The body is larger than the operation accepts. |

## 415

The body is not application/json.

| Code              | Meaning                                     |
| ----------------- | ------------------------------------------- |
| `door/media-type` | The body is not sent as `application/json`. |

## 422

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.                                  |

## 503

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.                                                |
