Errors

Overview

The Payment Links and Payment Intents endpoints use the same nested error envelope. Always branch on error.code, not on the wording of error.message, which can change between releases. For cross-cutting handling (HTTP status ranges, retry and reconciliation rules), see Errors.

Payment Links errors

The Payment Links API returns a nested envelope:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "amount must equal the sum of line items.",
    "details": {
      "field": "amount",
      "rule": "line_item_sum"
    },
    "correlation_id": "b7e2c1a4-9f3d-4c6b-8a21-5e0f7d9c3b18"
  }
}

Application errors include correlation_id (also returned as the x-correlation-id response header). Platform-generated authentication, authorization, and rate-limit errors use the same shape but do not include correlation_id.

Code	HTTP	Cause	What to do
`BAD_REQUEST`	400	A field is missing or invalid, or the request body could not be parsed (for example `amount` does not equal the line-item sum).	Fix the request body and retry.
`UNAUTHORIZED`	401	Missing or invalid API key.	Send a valid key in `X-API-Key`.
`FORBIDDEN`	403	The key is valid but is not enabled for this operation.	Use a key enabled for this operation.
`NOT_FOUND`	404	The link does not exist, or it belongs to a different entity than your key.	Confirm the id, and that the link is within your key’s entity scope. See the design note below.
`IDEMPOTENCY_MISMATCH`	409	The same `Idempotency-Key` was reused with a different request body.	Use a fresh key for a new operation, or resend the identical body to replay.
`STILL_PROCESSING`	409	A previous request with the same `Idempotency-Key` is still processing.	Wait a moment and retry with the same key.
`INVALID_STATE`	409	The operation is not valid for the link’s current state (for example cancelling a link that is no longer `ACTIVE`).	Re-read the link and act on its current `status`.
`REQUEST_TOO_LARGE`	413	The request body exceeds the maximum size.	Reduce the payload (for example fewer `line_items`).
`UNSUPPORTED_MEDIA_TYPE`	415	`Content-Type` is not `application/json`.	Set `Content-Type: application/json`.
`NO_PAYMENT_METHOD`	422	No eligible payment methods are configured for this branch.	Contact support to enable a payment method for the branch.
`INTERNAL_ERROR`	500	An unexpected error occurred on the Modulus side.	Retry with backoff; if it persists, contact support with the `correlation_id`.

Design note - why cross-tenant reads return 404, not 403. Requesting a link that belongs to another entity returns 404 NOT_FOUND, the same as an id that does not exist. A 403 would confirm the link exists, leaking information across tenants. Returning 404 gives no such existence oracle.

Hosted checkout and JavaScript SDK errors

Errors returned to the hosted checkout page and the JavaScript SDK use the same nested error object, with details.field naming the rejected input (for example bill_to.postal_code or card.number). For compatibility, these responses also repeat code, message, request_id, and details at the top level; read error. If you use the JavaScript SDK you do not parse these bodies yourself: branch on result.error.type (see Confirm payment). Customer and billing fields are limited to the lengths the card processor accepts, counted in characters:

Field	Max length
First name, last name	60
Address line 1, address line 2	60
City	50
State / province code	2-character subdivision code for US, CA, and CN
Postal code	10
Email	255
Phone	E.164, up to 15 digits

Postal codes must also match the country’s format when the billing country is one of these. A mismatch returns 400 with details.field bill_to.postal_code and details.rule postal_code_format. Other countries have only the length check. Postal code is optional.

Country	Format	Example
PH	Exactly 4 digits	`1226`
US	5 digits, or ZIP+4	`94105`, `94105-1234`
CA	Letter, digit, letter, space, digit, letter, digit	`A1B 2C3`

Payment Intents errors

The Payment Intents API uses the same nested envelope as Payment Links. Validation errors can include an optional details object with machine-readable context. Use details.field to identify the request field; the human-readable message does not repeat it as a prefix.

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "currency must be a supported ISO 4217 code.",
    "details": {
      "field": "currency",
      "rule": "supported"
    },
    "correlation_id": "b7e2c1a4-9f3d-4c6b-8a21-5e0f7d9c3b18"
  }
}

Code	HTTP	Cause	What to do
`BAD_REQUEST`	400	A field is missing or invalid. Inspect optional `details.field` and `details.rule`.	Correct the request and retry.
`INVALID_REQUEST_BODY`	400	The request body could not be parsed.	Send valid JSON matching the schema.
`MISSING_IDEMPOTENCY_KEY`	400	The `Idempotency-Key` header is required but was not sent.	Include an `Idempotency-Key` header.
`UNAUTHORIZED`	401	Missing or invalid secret key.	Send a valid secret key in `X-API-Key`.
`FORBIDDEN`	403	The key is valid but is not authorized for this resource.	Use a key with access to this entity scope.
`PAYMENT_INTENT_NOT_FOUND`	404	The intent does not exist or is outside the key’s entity scope.	Confirm the id and API-key hierarchy.
`IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_BODY`	409	The same `Idempotency-Key` was reused with a different request body.	Use a fresh key for a new operation, or resend the identical body to replay.
`PAYMENT_INTENT_TERMINAL`	410	The intent is no longer accepting payment.	Create a new intent.
`PAYLOAD_TOO_LARGE`	413	The request body exceeds the maximum size.	Reduce the payload.
`UNSUPPORTED_MEDIA_TYPE`	415	`Content-Type` is not `application/json`.	Set `Content-Type: application/json`.
`NO_ECOM_MID_FOR_BRANCH`	422	No eligible payment methods are configured for this branch.	Contact support to enable a payment method for the branch.
`INTERNAL_ERROR`	500	An unexpected error occurred on the Modulus side.	Retry with backoff; if it persists, contact support with the `correlation_id`.

Next Steps

Payment Links

Create and manage hosted checkout links

JavaScript SDK

Take card payments in the browser

Global errors

HTTP status ranges and retry rules

Testing

Test cards and error scenarios

Get Started

QR API

Webhooks API

Onboarding API

Terminal Gateway API

Transaction Reporting API

Ecom API

Shared Resources

Overview

Payment Links errors

Hosted checkout and JavaScript SDK errors

Payment Intents errors

Next Steps

Payment Links

JavaScript SDK

Global errors

Testing