Skip to main content

​
Error Response Format

All errors return a consistent JSON structure: 
{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "The currency field is required",
    "request_id": "req_a1b2c3d4e5f6"
  }
}

​
HTTP Status Codes

CodeDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Authentication failed
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
409Conflict - Resource already exists
422Unprocessable - Business logic error
429Rate Limited - Too many requests
500Server Error - Internal issue

​
Error Types

TypeDescription
authentication_errorInvalid API key or signature
authorization_errorInsufficient permissions
validation_errorInvalid request parameters
not_found_errorResource not found
conflict_errorDuplicate resource
rate_limit_errorToo many requests
api_errorInternal server error

​
Common Errors

​
Authentication Failed

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_signature",
    "message": "The request signature is invalid"
  }
}
Solution: Check your HMAC signature calculation.

​
Validation Error

{
  "error": {
    "type": "validation_error",
    "code": "missing_field",
    "message": "The amount field is required"
  }
}
Solution: Include all required fields in your request.

​
Rate Limited

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds"
  }
}
Solution: Implement exponential backoff and retry logic.

​
Error Handling Best Practices

try:
    response = client.post("/v1/transfers/payouts", data)
    return response.json()
except APIError as e:
    if e.type == "rate_limit_error":
        time.sleep(60)
        return retry_request()
    elif e.type == "validation_error":
        log_validation_error(e.message)
        return None
    else:
        raise