Error Codes

Reference for all error codes returned by the API.

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key or signature
403	Forbidden - IP not whitelisted or key disabled
404	Not Found - Resource doesn't exist
409	Conflict - Duplicate reference_id
422	Unprocessable - Validation failed
429	Too Many Requests - Rate limited
500	Internal Server Error

Error Codes

Authentication Errors

Code	Description
`UNAUTHORIZED`	Invalid or missing API key
`INVALID_SIGNATURE`	HMAC signature doesn't match
`API_KEY_DISABLED`	API key has been deactivated
`IP_NOT_WHITELISTED`	Request IP not in whitelist

Validation Errors

Code	Description
`VALIDATION_ERROR`	Request failed validation
`INVALID_AMOUNT`	Amount is invalid or out of range
`INVALID_CURRENCY`	Unsupported currency code
`MISSING_REQUIRED_FIELD`	Required field not provided

Business Errors

Code	Description
`USER_NOT_FOUND`	User identifier doesn't match any account
`INSUFFICIENT_BALANCE`	User doesn't have enough funds
`DUPLICATE_REFERENCE`	Reference ID already used
`CANNOT_CANCEL`	Resource cannot be cancelled in current state

Rate Limiting

Code	Description
`RATE_LIMIT_EXCEEDED`	Too many requests, slow down

Error Response Example

422 Unprocessable Entity

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": [
      {
        "field": "amount",
        "message": "The amount must be at least 1.00"
      },
      {
        "field": "currency",
        "message": "The selected currency is invalid."
      }
    ]
  }
}

Handling Errors

Always check the success field first
Use error.code for programmatic error handling
Display error.message to users
Retry on 5xx errors with exponential backoff

Previous Models

Next Signature Generator