Error reference

Every error code that the API returns, grouped by the shape of the error body.

On this page

How to read an error
Request errors
Transaction errors
Payment and refund errors
Checkout errors

How to read an error

Read the HTTP status first. It tells you whether a retry can help. See Errors.
Then read the code. The code is stable. Do not branch on message, which is for people and can change.
Keep the X-Request-Id response header with your logs. It identifies the request if you need help from Merxian.

Request errors#

Used by: Every endpoint. Merxian checks the API key, the scope, the Idempotency-Key header, the size of the request, and the rate limit before it runs the operation.

Shape: errorCode, message, and fieldErrors at the top level.

Example

{
  "errorCode": "InsufficientScope",
  "message": "This API key needs this scope: payments:refund.",
  "fieldErrors": []
}

Code	Status	Meaning and action
AuthenticationRequired	401	The API key is missing, malformed, revoked, or unknown, or its prefix is not `mx_sandbox_` or `mx_live_`. Check the `Authorization` header and the key prefix. Do not retry with the same key. Authentication
InsufficientScope	403	The API key does not hold the scope that the endpoint requires. Use a key with the scope that the message names. API key scopes
ValidationFailed	400	A create or command request has no `Idempotency-Key`, or the key has more than 200 characters. Send a valid `Idempotency-Key`. Idempotency
ValidationFailed	413	The request body is larger than 64 KiB. Send a smaller request. Rate limits
ResourceNotFound	404	The path does not exist. Check the method and the path. A `405` carries the same code and an `Allow` header.
RateLimited	429	The account sent too many requests. Wait for the seconds in `Retry-After`, then retry. Rate limits
UpstreamUnavailable	502, 503, 504	Merxian could not complete the request in time. Retry with the same `Idempotency-Key`, with backoff. Retries
InternalServerError	500	An unexpected error occurred. Retry with the same `Idempotency-Key`, with backoff. Retries

Transaction errors#

Used by: The /v1/transactions endpoints.

Shape: An error object with code, message, and an optional details map from field name to message.

Example

{
  "error": {
    "code": "revision_conflict",
    "message": "The transaction changed after revision 3."
  }
}

Code	Status	Meaning and action
bad_request	400	The request cannot be read, for example malformed JSON or an unknown filter value. Fix the request.
transaction_not_found	404	The transaction does not exist, or it belongs to another account. Check the ID and the environment of the API key.
idempotency_conflict	409	The `Idempotency-Key` was used before with a different request. Use a new key for a new request. Idempotency
revision_conflict	409	The transaction changed after the revision that you sent. Read the transaction again, then repeat the update with the new revision. Build a transaction
immutable	409	The transaction is finalized, so its commercial content cannot change. Add an adjustment, or cancel it and create a new transaction. Cancel or adjust a transaction
invalid_transition	409	The transaction is not in a state that allows the command. Read the transaction and check its `status`. Transaction lifecycle
not_collectible	409	The transaction cannot be collected in its current state. Finalize the transaction first, or check that it is not canceled or completed.
not_cancelable	409	The transaction has collected money or has a payment in progress. Refund the payment instead, or wait for the payment result. Cancel or adjust a transaction
validation_failed	422	A field is not valid. `details` names the field. Fix the field.
invalid_transaction	422	The transaction cannot be finalized with its current content, for example because tax needs a billing address. Read the message, complete the draft, and finalize again. Build a transaction
currency_mismatch	422	A line or an amount uses a different currency from the transaction. Use prices in the currency of the transaction. Money and currencies
amount_only_not_allowed	422	Your account calculates tax, so a transaction needs catalog lines, not only an amount. Send `lines` instead of `amount`. Products and prices
fx_rate_unavailable	422	Merxian has no exchange rate for the currency of the transaction, so it cannot calculate the fixed part of the fee. Use a currency that Merxian supports. `details.currency` names the currency. Fees
dependency_unavailable	503	Merxian could not complete the request now. The response has `Retry-After`. Retry with the same `Idempotency-Key`, with backoff. Retries
internal_error	500	An unexpected error occurred. Retry with the same `Idempotency-Key`, with backoff.

Payment and refund errors#

Used by: The /v1/payments and /v1/refunds endpoints, and List the payments of a transaction.

Shape: errorCode and message at the top level. A 404 from Retrieve a payment or Retrieve a refund has an empty body.

Example

{
  "errorCode": "refundValidationFailed",
  "message": "The refund amount is more than the refundable amount."
}

Code	Status	Meaning and action
invalidRequest	400	The request cannot be read, or it has a field that the endpoint does not accept. Fix the request. Payment endpoints refuse unknown fields.
AccountSuspended	403	Your account is suspended and cannot collect payments. Check the account state in the dashboard.
AccountClosed	403	Your account is closed. Check the account state in the dashboard.
paymentNotFound	404	The payment does not exist, or it belongs to another account. Check the ID and the environment of the API key.
transactionNotFound	404	The transaction does not exist, or it belongs to another account. Check the ID and the environment of the API key.
idempotencyConflict	409	The `Idempotency-Key` was used before with a different request. Use a new key for a new request. Idempotency
paymentValidationFailed	422	The payment cannot be created, for example because the transaction already has an active payment. Read the message. Read the payments of the transaction before you create another.
transactionContextRejected	422	The transaction cannot be collected, for example because it is not `ready`. Finalize the transaction, or check its state. Transaction lifecycle
refundValidationFailed	422	The refund is not valid: the payment does not exist or is not refundable, or the amount is more than the refundable amount. Read the payment and its refunded amount before you try again. Refund a payment
lifecycleValidationFailed	422	The payment does not exist, or its state does not allow the command. Read the payment and check its `status`. Payment lifecycle
providerRejected	422	The payment or refund was refused during processing. Do not retry the same request. For a payment, let the payer try again.
providerPending	503	The same request is still in progress. Retry later with the same `Idempotency-Key`, or wait for the webhook event. Asynchronous results

Checkout errors#

Used by: The /v1/checkout-sessions and /v1/payment-links endpoints.

Shape: The same shape as request errors: errorCode, message, and fieldErrors. Field names in fieldErrors are snake_case.

Example

{
  "errorCode": "ValidationFailed",
  "message": "The request is not valid.",
  "fieldErrors": [
    { "field": "success_url", "message": "must use https" }
  ]
}

Code	Status	Meaning and action
ValidationFailed	400, 422	A field is not valid. `fieldErrors` names each field. Fix the fields.
AccessDenied	403	The request is not allowed for your account. Check the account state in the dashboard.
ResourceNotFound	404	The session, the payment link, or a referenced transaction does not exist. Check the ID and the environment of the API key.
StaleIdempotencyKey	409	The `Idempotency-Key` was used before with a different request. Use a new key for a new request. Idempotency
TerminalSession	409	The session is `complete` or `cancelled`, so the command does not apply. Read the session. Create a new session if the buyer still wants to pay. Checkout session lifecycle
Conflict	409, 503	The request conflicts with the current state, or Merxian could not complete it now. For `409`, read the resource. For `503`, retry with the same key.
RateLimitExceeded	429	The account created too many checkout sessions in a short time. Slow down and retry with backoff. This response has no `Retry-After`. Rate limits
ServiceUnavailable	503	Merxian is busy. Retry with the same `Idempotency-Key`, with backoff.
InternalServerError	500	An unexpected error occurred. Retry with the same `Idempotency-Key`, with backoff.