application/problem+json. This includes authentication failures, unsupported methods and malformed JSON. A path that matches no endpoint is the one exception: it returns a plain 404 with an empty body.
The /lookup and /auth endpoints use a different format. See Other endpoints.
Extra fields
Two problem types add fields.validation-error adds errors, one entry per invalid field. pointer is a JSON Pointer into your request.
registration-info-required adds required and missing. Both are lists of JSON Pointers into your request: required is every registration field the route needs, and missing is the ones you still have to send.
Problem types
Each heading below is the slug at the end oftype.
invalid-request
400 Invalid request. The request is malformed: bad JSON, an unknown enum value, a bad path or query parameter, or a value that fails a check (for example a CLABE check digit, a non-positive amount, or a pageSize outside 1 to 100). Fix the request. detail names the problem.
validation-error
400 Your request is not valid. One or more fields are missing, not allowed, or malformed. Fix each field listed in errors.
quote-expired
400 Quote expired. The quote passed to POST /organization/{organizationId}/order has expired or does not exist. Create a new quote and use its quoteId.
amount-out-of-range
400 Amount out of range. The amount is below the minimum or above the maximum of a rail. Change the amount. The account’s rails show minAmount and maxAmount when a limit is known.
sandbox-limit-exceeded
400 Sandbox limit exceeded. The amount exceeds the sandbox limit for onramps (500 MXN per quote). Use a smaller amount in sandbox. See the Sandbox Reference.
unauthorized
401 Unauthorized. The Authorization header is missing, not ASCII, or does not hold a valid API key. Send the raw API key with no Bearer prefix, for the right environment. See Authentication.
forbidden
403 Forbidden. The request is not allowed here, for example the sandbox simulator called in production, member endpoints called for your own organization, or partner statements read with a customer organization’s key. Do not retry.
not-found
404 Not found. The resource does not exist or does not belong to the organization in the route, or the organizationId in the route is an organization your API key cannot act for. A path that matches no endpoint also returns 404, with an empty body. Your key can act for its own organization and its direct customer organizations. Check the ids and the path.
method-not-allowed
405 Method not allowed. The route exists but not for this HTTP method. The Allow header lists the methods it accepts. Use a method from Allow.
conflict
409 Conflict. The request collides with existing state: a webhook subscription for this URL and event already exists, an order for this quote was created at the same time, the account is registered in a different market, an organization id is already in use, or a customer’s verification is not at a stage that accepts this write. detail says which. Read the existing resource instead of creating it again. See Idempotency.
organization-not-approved
409 Organization not approved. The organization in the route is not approved, so it cannot quote. Complete verification, then quote again.
payment-account-unavailable
409 Payment account unavailable. Another organization holds this account. Register a different account.
payment-account-disabled
409 Payment account disabled. The account is disabled. It cannot be registered or quoted. Use a different account.
payment-account-not-ready
409 Payment account not ready. The account is not ready in the needed direction on the chosen rail, is not registered on the rail you named, or has no rail that can carry that direction. Check the account’s rails. Wait for the direction to become ready, or name a rail the account is ready on.
order-not-cancelable
409 Order not cancelable. The order can no longer be canceled, for example it already finished. Read the order to see its status.
order-not-claimable
409 Order not claimable. The order is not claimable, so there is nothing to claim. Read the order to see its status.
authorization-expired
409 Authorization expired. The id you sent is not the order’s current authorization, or it expired. Read the order, sign the new authorization.method.message, and send the new id.
authorization-not-required
409 Authorization not required. The order has no pending authorization. Read the order to see its current state.
invalid-signature
400 Invalid signature. The signature is not valid hex, or it does not verify over the authorization’s message with the embedded wallet’s signerPublicKey. Sign the exact UTF-8 bytes of message with ECDSA P-256 and SHA-256, and send it as DER or r||s hex.
payload-too-large
413 Payload too large. The request body is too large. Send a smaller body.
rate-limit-exceeded
429 Rate limit exceeded. You sent too many requests, for example balance reads for one organization. Wait the number of seconds in the Retry-After header, then send the request again.
quote-unavailable
422 Quote unavailable. We cannot price this route right now. Retry later with backoff.
registration-info-required
422 Registration information required. The route requires registration fields we do not hold and you did not send. Send the fields listed in missing under registrationInfo.
holder-tax-id-mismatch
422 Account holder tax ID mismatch. registrationInfo.taxId does not match the verified tax ID. Send the verified tax ID, or leave taxId out and we use the verified one.
unsupported
422 Unsupported. The operation is not supported, for example a debitCard account, an identifier no route accepts, a route we cannot quote, or a sandbox deposit simulation on an order whose source does not receive fiat. Do not retry the same request. Change the account or route.
internal-error
500 Internal server error. An unexpected error on our side. Retry with backoff. If it persists, contact support with the instance.
not-implemented
501 Not implemented. The endpoint is documented but not available yet in this environment. Do not retry. Check the changelog for when it ships.
service-unavailable
503 Service unavailable. A dependency is temporarily unavailable. Retry with backoff.
Handling errors
- Handle errors by
type. Usestatusas a fallback for unknown types. 4xxother thanquote-unavailableandrate-limit-exceeded: fix the request before retrying. The same request fails the same way.rate-limit-exceeded: retry afterRetry-After.quote-unavailable,internal-errorandservice-unavailable: retry with exponential backoff.POST /organization/{organizationId}/orderis safe to retry with the samequoteId; it returns the existing order instead of creating a second one.- Keep the
instanceof any error you report to support.
Other endpoints
The/lookup and /auth endpoints do not return problem details. /lookup returns an HTTP status code with a short message, as plain text or as a JSON object { "error": "<message>" }. /auth/token returns OAuth 2.0 errors; see Authentication errors. Handle these by HTTP status code, and display or log the message rather than using it as an error code.
The KYC verification endpoints list every missing or invalid field in one 400 detail. Fill them in and send the request again; the call is safe to repeat. See KYC API error handling.
Still stuck? Book a session with the team.