Error Codes

All API errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

Error Reference

Code	HTTP Status	Description
VALIDATION_ERROR	400	Invalid request data. Check the request body and query parameters.
INSUFFICIENT_FUNDS	400	Insufficient wallet balance to complete the operation.
AUTHENTICATION_ERROR	401	Invalid or missing API key. Ensure the Authorization header is set correctly.
NOT_FOUND	404	The requested resource does not exist.
IDEMPOTENCY_ERROR	422	An idempotency conflict occurred. The same idempotency key was used with different request parameters.
RATE_LIMIT_ERROR	429	Rate limit exceeded. Back off and retry after the period indicated in the Retry-After header.

Handling Errors

All error responses include a code field that you can use for programmatic error handling, and a message field with a human-readable description.

try {
  const payout = await client.payouts.create({ ... });
} catch (err) {
  switch (err.code) {
    case 'VALIDATION_ERROR':
      // Fix request parameters
      break;
    case 'INSUFFICIENT_FUNDS':
      // Top up wallet balance
      break;
    case 'RATE_LIMIT_ERROR':
      // Retry after delay
      break;
    default:
      // Unexpected error
      break;
  }
}