Error Codes

Error codes returned in API responses and how to resolve them.

HTTP Status Codes

Code	Description
200	Success
201	Created
202	Accepted (async processing)
400	Bad Request (parameter error)
401	Unauthorized (key error)
403	Forbidden
404	Not Found
409	Conflict (duplicate request)
500	Internal Server Error

Error Response Format

{
  "code": "ERROR_CODE",
  "message": "Human readable message",
  "details": [...]
}

---

Authentication Errors (401)

UNAUTHORIZED

API Key or Public Key is invalid or missing.

{ "code": "UNAUTHORIZED", "message": "Invalid or missing API key" }

---

Validation Errors (400)

INVALID_REQUEST

General invalid request error.

{ "code": "INVALID_REQUEST", "message": "Invalid request" }

VALIDATION_ERROR

{
  "code": "VALIDATION_ERROR",
  "message": "Input validation failed",
  "details": [{ "path": ["amount"], "message": "Expected number, received string" }]
}

UNSUPPORTED_CHAIN

{ "code": "UNSUPPORTED_CHAIN", "message": "Unsupported chain" }

Resolution: Check supported chains via GET /chains

CHAIN_NOT_CONFIGURED

{ "code": "CHAIN_NOT_CONFIGURED", "message": "Merchant chain is not configured" }

CHAIN_MISMATCH

{ "code": "CHAIN_MISMATCH", "message": "Token does not belong to merchant chain" }

TOKEN_NOT_ENABLED

{
  "code": "TOKEN_NOT_ENABLED",
  "message": "Token is not enabled for this merchant. Add and enable it in payment methods first."
}

Resolution: Add and enable the token via POST /merchant/payment-methods

INVALID_PAYMENT_STATUS

Returned when a gasless (relay) request is sent for a payment that is already in a non-CREATED state. Gasless is only allowed when payment status is CREATED.

{
  "code": "INVALID_PAYMENT_STATUS",
  "message": "Payment is in terminal state (e.g. PAID, REFUNDED, EXPIRED). Gasless requests only allowed when status is CREATED."
}

PAYMENT_EXPIRED

{ "code": "PAYMENT_EXPIRED", "message": "Payment has expired" }

INVALID_STATUS (Refund)

Returned when calling POST /refunds and the payment is not in PAID status.

{
  "code": "INVALID_STATUS",
  "message": "Payment must be PAID to request a refund. Current status: REFUNDED"
}

Resolution: Only request a refund when GET /payments/:id returns status === "PAID".

INVALID_SIGNATURE

{ "code": "INVALID_SIGNATURE", "message": "Invalid signature format" }

Resolution: Ensure signature is a hex string starting with 0x. Verify EIP-712 domain (name: 'ERC2771Forwarder', version: '1').

RELAYER_NOT_CONFIGURED

{ "code": "RELAYER_NOT_CONFIGURED", "message": "No relayer configured for chain 80002" }

RECIPIENT_NOT_CONFIGURED

{ "code": "RECIPIENT_NOT_CONFIGURED", "message": "Merchant recipient address is not configured" }

INVALID_CURRENCY

{ "code": "INVALID_CURRENCY", "message": "Unsupported currency: XYZ" }

UNSUPPORTED_TOKEN

Token exists but is not supported on this chain.

{ "code": "UNSUPPORTED_TOKEN", "message": "Unsupported token" }

TOKEN_INFO_ERROR

Failed to fetch token information from the blockchain.

{ "code": "TOKEN_INFO_ERROR", "message": "Failed to fetch token info" }

PRICE_SERVICE_NOT_CONFIGURED

Currency conversion was requested but the price service is not available.

{ "code": "PRICE_SERVICE_NOT_CONFIGURED", "message": "Price service is not configured" }

PAYER_ADDRESS_NOT_FOUND

Payer wallet address could not be resolved.

{ "code": "PAYER_ADDRESS_NOT_FOUND", "message": "Payer address not found" }

RELAY_ALREADY_SUBMITTED

Returned when a gasless relay has already been submitted for this payment.

{
  "code": "RELAY_ALREADY_SUBMITTED",
  "message": "Gasless already submitted for this payment. Check relay status or use a new checkout."
}

AMOUNT_MISMATCH

Returned when the amount in the relay request does not match the payment amount in the database.

{ "code": "AMOUNT_MISMATCH", "message": "Payment amount mismatch" }

PAYMENT_NOT_PAID

Returned when requesting a refund for a payment that is not in PAID status.

{ "code": "PAYMENT_NOT_PAID", "message": "Payment must be PAID to request a refund" }

---

Not Found Errors (404)

TOKEN_NOT_FOUND

{ "code": "TOKEN_NOT_FOUND", "message": "Token not found or not whitelisted for this chain" }

PAYMENT_NOT_FOUND

{ "code": "PAYMENT_NOT_FOUND", "message": "Payment not found" }

NOT_FOUND

Generic resource not found.

{ "code": "NOT_FOUND", "message": "Resource not found" }

CHAIN_NOT_FOUND

{ "code": "CHAIN_NOT_FOUND", "message": "Chain not found" }

RELAY_NOT_FOUND

{ "code": "RELAY_NOT_FOUND", "message": "No relay request found for this payment" }

REFUND_NOT_FOUND

{ "code": "REFUND_NOT_FOUND", "message": "Refund not found" }

---

Conflict Errors (409)

DUPLICATE_ORDER

{ "code": "DUPLICATE_ORDER", "message": "Order ID already used for this merchant." }

PAYMENT_METHOD_EXISTS

Payment method already exists for this merchant and token.

{ "code": "PAYMENT_METHOD_EXISTS", "message": "Payment method already exists" }

PAYMENT_ALREADY_REFUNDED

{ "code": "PAYMENT_ALREADY_REFUNDED", "message": "Payment has already been refunded" }

CONFLICT (Refund)

Returned when POST /refunds is called while another refund request is already processing the same payment.

{
  "code": "CONFLICT",
  "message": "Payment is already being processed by another request"
}

Resolution: Wait and poll GET /payments/:id until status is REFUNDED; do not retry the refund immediately.

REFUND_IN_PROGRESS

Returned when a refund is already in progress for this payment.

{ "code": "REFUND_IN_PROGRESS", "message": "A refund is already in progress for this payment" }

---

Forbidden Errors (403)

FORBIDDEN

{ "code": "FORBIDDEN", "message": "Payment does not belong to this merchant" }

---

Server Errors (500)

CHAIN_CONFIG_ERROR

Returned when the chain or relayer configuration is missing or invalid.

{ "code": "CHAIN_CONFIG_ERROR", "message": "Chain or relayer configuration error" }

MERCHANT_CHAIN_NOT_CONFIGURED

Merchant's chain configuration is missing.

{ "code": "MERCHANT_CHAIN_NOT_CONFIGURED", "message": "Merchant chain is not configured" }

SIGNATURE_ERROR

Server failed to generate a signature.

{ "code": "SIGNATURE_ERROR", "message": "Signature generation failed" }

SIGNING_SERVICE_ERROR

Returned when the server fails to generate a required signature.

{ "code": "SIGNING_SERVICE_ERROR", "message": "Failed to generate signature" }

RELAYER_ERROR

Returned when the relayer fails to submit a transaction to the blockchain.

{ "code": "RELAYER_ERROR", "message": "Relayer failed to submit transaction" }

INTERNAL_ERROR

{ "code": "INTERNAL_ERROR", "message": "An internal error occurred" }

Next Steps

• Webhooks - Event-based processing