Error Reference

Every error returned by the External Payments API uses a single structured envelope. This page documents the envelope, the response headers that accompany errors, and every error code the API can return.

Error Envelope

All errors are returned as JSON with a single top-level error object:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "errorCode": "E1002",
    "message": "property payer should not exist",
    "param": "payer",
    "docUrl": "https://docs.miraclecash.info/errors#E1002",
    "userSafeMessage": false,
    "requestId": "8f14e45f-ceea-4f3a-9a5a-1c0d2e3f4a5b"
  }
}

Envelope Fields:

Field	Type	Description
`type`	string	The broad error category. See Error Types below.
`code`	string	Machine-readable error slug (e.g. `parameter_unknown`). Use this for programmatic error handling.
`errorCode`	string	Short alphanumeric code (e.g. `E1002`) for support and documentation references.
`message`	string	Human-readable, developer-facing description of what went wrong.
`param`	string	The request parameter the error relates to, when applicable. Omitted otherwise.
`docUrl`	string	Link to the documentation section for this error code.
`userSafeMessage`	boolean	`true` when `message` is safe to display to your end customer as-is. When `false` (the default for almost all codes), treat `message` as developer-facing and show your own copy to customers.
`requestId`	string	Unique ID of this request. Include it when contacting support about an error.

Response Headers

Header	Description
`X-MP-Should-Retry`	`true` means the exact same request may succeed if repeated (the failure is transient — e.g. rate limiting, clock skew, an internal error). `false` means the request must be changed before retrying.
`Retry-After`	Present on `429` rate-limit responses and on `409` idempotency in-progress responses (E4003). Number of seconds to wait before retrying.

Error Types

Type	Description
`invalid_request_error`	The request body, parameters, or referenced resources are invalid.
`authentication_error`	The request signature, API key, timestamp, or nonce failed verification.
`permission_error`	The API key is valid but lacks the scope required by the endpoint.
`idempotency_error`	A problem with the `Idempotency-Key` header or a conflicting replay.
`rate_limit_error`	Too many requests — slow down and retry after the window clears.
`api_error`	Something failed on MiraclePay's side. Safe to retry.

Error Codes

Validation Errors (E1xxx)

invalid_request (E1000)

HTTP 400 · invalid_request_error · Retry: no

The request is malformed in a way not attributable to a single parameter — for example an unreadable JSON body. Fix the request before retrying.

parameter_invalid (E1001)

HTTP 400 · invalid_request_error · Retry: no

A request parameter failed validation — wrong type, out of range, or an invalid combination (e.g. passing both startingAfter and endingBefore). The param field names the offending parameter and message contains the validation detail.

parameter_unknown (E1002)

HTTP 400 · invalid_request_error · Retry: no

The request contains a field the API does not recognize. Unknown fields are rejected, not silently ignored — remove the field named in param.

redirect_domains_not_configured (E1010)

HTTP 400 · invalid_request_error · Retry: no

You passed a redirectUrl but your merchant account has no allowed redirect domains configured. Add the domain in the dashboard under Developer Settings first.

redirect_url_invalid (E1011)

HTTP 400 · invalid_request_error · Retry: no

The redirectUrl is not a valid URL (or is not https where required). Fix the URL format.

redirect_domain_not_allowed (E1012)

HTTP 400 · invalid_request_error · Retry: no

The hostname of the redirectUrl is not on your allowed redirect domains list. The hostname must exactly match one of the configured domains.

blockchain_not_configured (E1020)

HTTP 400 · invalid_request_error · Retry: no

One or more of the requested blockchainIds are not available for your merchant account — either the network is not active or no payment address is configured for it. Use GET /external/v1/blockchains/active to see which networks you can accept, and configure the missing ones in the dashboard.

merchant_not_configured (E1030)

HTTP 400 · invalid_request_error · Retry: no

Your merchant account is missing configuration required to create payments (for example, no main branch). The message explains what is missing; contact support if unclear.

conflict (E1040)

HTTP 409 · invalid_request_error · Retry: no

The request conflicts with the current state of a resource. Inspect the message for detail.