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" }INSUFFICIENT_TOKEN_BALANCE
Returned by POST /payments/request-gas when the wallet token balance is below the payment amount.
{
"code": "INSUFFICIENT_TOKEN_BALANCE",
"message": "Token balance is less than payment amount"
}ALREADY_HAS_GAS
Returned when the wallet already has enough native token for the approve transaction.
{ "code": "ALREADY_HAS_GAS", "message": "Wallet already has enough gas for approve" }ALREADY_GRANTED
Returned when this wallet already received a gas grant on this chain.
{
"code": "ALREADY_GRANTED",
"message": "This wallet already received a gas grant for this chain"
}PAYMENT_ALREADY_GRANTED
Returned when this payment already funded a gas grant (one payment funds at most one grant).
{
"code": "PAYMENT_ALREADY_GRANTED",
"message": "This payment has already funded a gas grant"
}Resolution: Create a new payment or use a wallet that has not yet consumed this payment's grant.
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" }GRANT_IN_PROGRESS
Returned by POST /payments/request-gas when another grant request for the same payment is in progress.
{
"code": "GRANT_IN_PROGRESS",
"message": "A gas grant for this payment is already in progress. Retry shortly."
}Forbidden Errors (403)
FORBIDDEN
{ "code": "FORBIDDEN", "message": "Payment does not belong to this merchant" }Also returned when the Origin header does not match ALLOWED_WIDGET_ORIGIN on public-key endpoints (including POST /payments/request-gas).
FAUCET_DISABLED
Returned by GET /payments/:id/gas-status and POST /payments/request-gas when the merchant does not have faucet support enabled.
{ "code": "FAUCET_DISABLED", "message": "Faucet is not enabled for 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