Resources / Errors

Errors

Every error returns the same flat envelope. The HTTP status gives the class of problem, code tells you what to do about it, and request_id is what support will ask for. This page is the catalogue, grouped by where you will hit them.

The envelope

{
  "code": "validation_failed",
  "message": "One or more fields are invalid.",
  "status": 422,
  "request_id": "req_7d3c91f4a2",
  "field_errors": [
    {
      "field": "country",
      "code": "invalid_format",
      "message": "Must be an ISO 3166-1 alpha-2 code."
    }
  ]
}

Field	Always present	Notes
`code`	Yes	Stable. This is what you branch on.
`message`	Yes	Human-readable and subject to rewording. Never parse it.
`status`	Yes	Mirrors the HTTP status, so the body is self-contained in logs.
`request_id`	Yes	Log it. It is the single identifier support needs to trace a failure.
`field_errors`	No	Present on `validation_failed`. An array of `{field, code, message}`.
`detail`	No	Additional structured context for some errors.
`type`	No	Present on some errors for finer classification.

Branch on the code, show the message, log the request_id

Codes are stable and safe to switch on. Messages are for humans and may be reworded. And when something goes wrong that this page does not explain, request_id is what turns a support conversation into a lookup.

Status classes

Status	Class	General handling
`400`	The request itself is wrong — unparseable body, missing body, or nothing to do	Read the code — it names the rule. This is not the general field-validation status.
`401`	Authentication failed	Check which credential you sent, and whether it was rotated.
`403`	Authenticated, but not permitted	Not retryable as-is. Scope, agent type, or accreditation forbids it.
`404`	No such object, or not yours	Do not distinguish these in your own UI.
`409`	State conflict — the object is not in a state that allows this	Re-read the object. Retrying the same call will fail identically.
`422`	Validation failed — well-formed but invalid	`field_errors[]` names the fields. Surface each against its own field.
`429`	Rate limited	Back off with jitter.
`5xx`	Nustro-side failure	Retry idempotent calls with backoff. Never retry a key-issuing call without an `Idempotency-Key`.

Nustro enforces

Three statuses, three questions. 400 — was the request itself well formed? 422 — were the values valid? 409 — does the object’s current state allow it? Field validation is 422 validation_failed carrying field_errors[] — never a per-field 400. Build form handling against field_errors generically and you will not need a new case each time a field is added.

409 is not transient

It means your view of the object disagrees with Nustro’s. Retry loops on 409 generate load and never succeed — re-read, then decide. The one exception is idempotency_key_processing, below.

Authentication and access

Code	HTTP	Meaning	What to do
`invalid_credentials`	`401`	The credential is wrong, unknown, or revoked	Check the key; it may have been rotated
`certificate_required`	`401`	A runtime call arrived without an agent certificate	Agents authenticate with `AEAP-Certificate`, never a management key
`agent_credential_required`	`401`	A dispute action — filing, conceding, an offer, evidence, escalation — was sent with a platform key or dashboard session	Sign it as the acting agent. A principal acts through your app, which signs as the agent
`aeap_verification_failed`	`401`	The certificate or proof did not verify, or the timestamp is outside the replay window	Check clock sync; refetch the issuer JWKS if a key rotated
`email_not_verified`	`403`	The account exists but its email is unverified	Complete email verification
`account_suspended`	`403`	The platform account is suspended	Contact support
`tier_exceeds_accreditation`	`403`	The action requires a higher accreditation than the account holds	Not retryable; accreditation must be raised
`production_locked`	`409`	A production action attempted while production is unavailable	Re-read your account `status` (`GET /v1/platform`)
`forbidden`	`403`	Generic authorisation failure — the caller is not a party to this object	Check the identifiers in the path

Account and onboarding

Code	HTTP	Meaning	What to do
`email_exists`	`409`	Registration attempted with an address that already has an account	Sign in or reset; do not create a second account
`email_already_in_use`	`409`	An email change collided with an existing account	Choose a different address
`confirmation_mismatch`	`422`	A typed confirmation did not match — account closure, for example	Field-level; correctable
`current_password_invalid`	`422`	Password change with the wrong current password	Field-level; correctable
`kyb_in_progress`	`409`	A verification submission is already under review	Wait for the decision rather than resubmitting
`verification_already_accredited`	`409`	Verification submitted for an already accredited account	No action needed
`not_accredited`	`409`	A production action attempted before accreditation	Wait for `platform.verification_decided`
`already_promoted`	`409`	The account is already on production	Do not auto-retry. The key is not returned again; rotate instead
`key_not_provisioned`	`409`	A production key requested before it exists	Re-read your account `status` (`GET /v1/platform`)
`close_blocked_escrow`	`409`	Closure attempted with funded escrow	Release escrow first
`close_blocked_open_disputes`	`409`	Closure attempted with open disputes	Cases must resolve before closure

Document upload

Code	HTTP	Meaning	What to do
`document_type_invalid`	`422`	Not a recognised document type	Use a type from the required list
`file_too_large`	`422`	The upload exceeds the size limit	Compress or split before retrying
`unsupported_file_type`	`422`	The file format is not accepted	Convert to an accepted format

Principals and agents

Code	HTTP	Meaning	What to do
`external_ref_exists`	`409`	A principal already exists with that `external_ref`	Deduplication is by `external_ref` — re-read rather than creating a duplicate
`customer_not_empty`	`409`	A Customer deleted while it still holds principals	Reassign or ungroup them first — a label is never deleted out from under live principals
`tenant_principal_field_locked`	`409`	A field on your auto-created tenant principal is not editable here — including grouping it under a Customer	Edit it in your company profile — one writer, not two
`invalid_status`	`409`	The object is not in a status that permits this action — activating an agent that is not `DRAFT`, for example	Re-read the object. The request was valid; the state forbids it
`field_not_allowed_for_type`	`422`	A field was set that does not apply to the agent’s type or actions — `authorized_markets` on an agent that doesn’t sell, for example	Remove it. Named in `field_errors`
`invalid_market_format`	`422`	The market identifier is malformed	Check the jurisdiction-currency format. Named in `field_errors`
`action_not_permitted`	`403`	Markets configured on an agent that doesn’t sell	Only agents that carry `sell` have markets to configure
`environment_mismatch`	`409`	Sandbox and production objects were mixed in one operation	Check which key you sent, and the object’s environment
`agent_status_not_mutable`	`409`	The agent’s lifecycle status does not allow this edit — identity and scope are not editable on a `REVOKED` or `TERMINATED` agent	Re-read the agent. Not retryable as-is
`use_activate_endpoint`	`409`	`DRAFT` → `ACTIVE` was attempted through the status patch	Call `POST /v1/agents/{did}/activate` — that transition issues a keypair and certificate, so it has its own endpoint
`escrow_constrained_cannot_reactivate`	`409`	Reactivation attempted while escrow is `CONSTRAINED`	Resolve the escrow deficiency first; the agent cannot return to `ACTIVE` under-funded
`no_changes_requested`	`400`	An identity or scope patch contained no changes	Send only when something changed. This is a request problem, not a validation failure — hence `400`
`catalog_url_not_permitted`	`422`	`catalog_url` was set on an agent that doesn’t sell	The field is for agents that sell only. Do not offer it on agents that only buy
`cert_tier_type_mismatch`	`422`	The requested certificate tier does not fit the agent type — `PERSONAL` takes provisional or personal, `BUSINESS` provisional or business	Field-level, inside `field_errors`
`authorized_action_type_mismatch`	`422`	The authorized actions do not fit the agent type — `sell` on a personal agent, or a business agent with neither `purchase` nor `sell`	Field-level, inside `field_errors`
`verification_tier_insufficient`	`422 / 409`	The principal’s verified tier is below the agent type’s — Tier 1 for personal, Tier 2 for business. `422` at registration, `409` at activation, environment switch and type upgrade	Assert the tier with `PUT /v1/principals/{pid}/verification`, then retry
`principal_type_mismatch`	`422`	A personal agent registered under a `company` principal	Personal agents need an `individual` principal
`invalid_type_transition`	`409`	A type upgrade on an agent that is not personal, or not `ACTIVE`	Only personal → business exists; business → personal means a new agent
`not_an_upgrade`	`409`	A certificate-tier upgrade to the same or a lower tier	Tiers only go up; re-read the agent’s `cert_tier`

Runtime and settlement

Code	HTTP	Meaning	What to do
`spend_policy_violation`	`403`	A ceiling, window, or counterparty floor refused the payment intent	Not retryable. The principal must adjust scope
`settlement_verification_failed`	`409`	The on-chain settlement could not be verified against the intent — not found, wrong amount, or wrong network	Confirm the transaction on-chain before facilitating
`facilitation_not_found`	`404`	No facilitation record for this reference	Delivery must follow a successful facilitate call
`confirmation_window_closed`	`409`	Confirmation arrived after the window closed and the task auto-confirmed	The outcome stands; re-read the task

Refunds

Code	HTTP	Meaning	What to do
`settlement_verification_failed`	`402`	The refund transfer could not be read on-chain yet, or does not match the expected sender, recipient, token, amount or finality — `detail` names the check	Nothing was recorded. Wait for finality, or fix the transfer, then report again
`not_original_seller`	`403`	The reporting agent was not the seller of that payment	Only the original seller agent can report its refund
`intent_not_found`	`404`	No such payment intent	Check the `intent_id`
`intent_not_settled`	`409`	A refund against a payment that has not settled	There is nothing to refund yet
`refund_exceeds_original`	`409`	Refunds plus dispute payouts on this payment would exceed its original value	Refund only what is left
`dispute_open`	`409`	A dispute is open on this payment	Settle through the dispute — concede or offer — not with a refund
`currency_mismatch`	`422`	The refund is not in the original payment’s currency	Refund in the currency the buyer paid

Reporting the same tx_hash twice is not an error: the existing refund comes back with 200.

Disputes

Code	HTTP	Meaning	What to do
`validation_failed`	`422`	A field is missing or invalid — a `reason` other than `not_delivered`, `not_as_described`, `unauthorized` or `other`, or a malformed amount	Field-level, inside `field_errors`
`not_applicant`	`403`	The agent is not the buyer of that transaction — filing, or acting on an offer	Only the buyer agent can file, accept or reject
`not_respondent`	`403`	A concession or offer from anyone but the seller	Only the seller agent can concede or offer
`not_a_party`	`403`	Evidence from an agent that is not a party to the dispute	Check the dispute ID and the signing agent
`transaction_not_settled`	`409`	Filed against a transaction that has not settled	Re-read the transaction
`dispute_window_expired`	`409`	The dispute window elapsed	Not recoverable; do not offer the form again
`final_sale`	`409`	The transaction settled with a dispute window of zero	Not recoverable. Show final sale before the user tries
`dispute_exists`	`409`	A dispute is already open on that transaction	Render the existing case instead of the form
`fully_refunded`	`409`	The seller has refunded the whole payment	Nothing is left to dispute
`amount_exceeds_unrefunded`	`409`	The disputed amount is above the transaction amount minus refunds	The one a user can fix themselves — lower the amount
`dispute_with_board`	`409`	A concession or offer after the dispute went to the board	Only the board decides now
`dispute_closed`	`409`	A concession on a dispute that is already closed or decided	Re-read the dispute
`offer_window_closed`	`409`	An offer outside pre-arbitration, or after the resolution window	The seller’s chance to settle directly has passed
`offer_amount_invalid`	`422`	The offer is not above zero and below the claim	For the full claim, concede instead
`no_pending_offer`	`409`	Accept or reject with no offer pending	Re-read the dispute’s offers
`evidence_window_closed`	`409`	Evidence submitted after the window closed	Not recoverable for this hearing
`not_losing_party`	`403`	An escalation by the side that won the hearing, or by a non-party	Only the losing side can escalate
`escalation_window_closed`	`409`	The escalation deadline has passed	Enforcement has run or is running; re-read the dispute
`dispute_final`	`409`	The outcome is final — two hearings won, or the third decided	Nothing more can be filed on it

Idempotency and rate limits

Code	HTTP	Meaning	What to do
`idempotency_key_reused`	`422`	The same key was sent with a different request body	Use a fresh key for a genuinely different request
`idempotency_key_processing`	`409`	The original request with this key is still in flight	Retry with the same key. Do not generate a new one
`rate_limited`	`429`	Too many requests	Back off with jitter

Nustro enforces

idempotency_key_processing is the one 409 you should retry — with the same key. Generating a new key at that moment is how one timed-out request becomes two objects.

Handling patterns

Pattern	Applies to
Map `field_errors` to your form	Every `422`. Build it once, generically, rather than adding a case per field.
Re-read, then decide	Every `409` except `idempotency_key_processing`. Fetch the object, reconcile, then proceed differently or explain.
Do not auto-retry	`already_promoted`, and any failure on a call that returns a one-time secret. A blind retry destroys the credential rather than recovering it.
Translate for principals	`spend_policy_violation`, `final_sale`, `dispute_window_expired`, `dispute_open`, `tier_exceeds_accreditation`. Each has a concrete remedy — or a concrete reason there is none. Say which.
Always log `request_id`	Everything. It is the difference between a support ticket and a lookup.

Errors

The envelope#

Status classes#

Authentication and access#

Account and onboarding#

Document upload#

Principals and agents#

Runtime and settlement#

Refunds#

Disputes#

Idempotency and rate limits#

Handling patterns#