Errors

All API errors use the same JSON shape:

{
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Human-readable message"
  }
}

Use error.code for programmatic handling. message is for logs and debugging.

HTTP status

Status	Typical meaning
`400`	Validation / bad request
`401`	Missing or invalid API key
`403`	Not allowed (e.g. live not approved)
`404`	Resource not found
`409`	Conflict (e.g. idempotency mismatch)
`429`	Rate limit exceeded
`500`	Unexpected server error

Code	Status	When
`UNAUTHORIZED`	401	Missing or invalid credentials
`INVALID_API_KEY`	401	Unknown or revoked API key
`RATE_LIMITED`	429	Over 100 requests/minute

Code	Status	When
`INVALID_AMOUNT`	400	Amount not a positive decimal string (max 6 decimal places)
`INVALID_METADATA`	400	Metadata is not a JSON object
`INVALID_NETWORK`	400	`networkId` invalid or unknown
`INVALID_TOKEN`	400	`token` not `USDC` or `USDT`
`NETWORK_NOT_ENABLED`	400	Network not available for this merchant/environment
`TOKEN_NOT_SUPPORTED_ON_NETWORK`	400	Token not available on the requested network
`NO_AVAILABLE_PAYMENT_METHOD`	400	Constraints leave no valid network/token
`ENVIRONMENT_NOT_ALLOWED`	400	Request included `environment` (omit it — use the key)
`IDEMPOTENCY_KEY_REQUIRED`	400	Missing `Idempotency-Key` on create
`IDEMPOTENCY_CONFLICT`	409	Same key, different body
`LIVE_NOT_APPROVED`	403	Live invoice / live key before go-live approval
`MERCHANT_SUSPENDED`	403	Merchant account is suspended
`INVOICE_NOT_FOUND`	404	Unknown invoice

Code	Status	When
`INVALID_WEBHOOK_URL`	400	Bad URL or live URL not public HTTPS
`INVALID_WEBHOOK_SECRET`	400	Secret length out of range
`WEBHOOK_SECRET_REQUIRED`	400	First setup without secret
`WEBHOOK_NOT_CONFIGURED`	404	No endpoint for that environment
`DELIVERY_NOT_FOUND`	404	Unknown delivery id

POST /v1/invoices (and partner creates) require Idempotency-Key.

Generate a fresh key per distinct create attempt (UUID is fine).

Default: 100 requests/minute per API key. On 429, retry with backoff.