Skip to main content
The SeamlessOS API uses standard HTTP status codes and provides structured error responses to help you understand and resolve issues with your requests.

​
Error Response Structure

All error responses follow a consistent structure with both human-readable messages and machine-readable codes: 
{
  "message": "Validation failed for the request",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "message": "Email address is required",
      "code": "FIELD_REQUIRED",
      "property": "email"
    },
    {
      "message": "Msisdn format is invalid",
      "code": "INVALID_FORMAT",
      "property": "msisdn"
    }
  ],
  "hint": "Ensure all required fields are provided with valid values"
}

​
Error Fields

message (required): A human-readable description of the error suitable for displaying to developers or in logs. code (required): A machine-readable error code that remains consistent across similar errors, enabling programmatic error handling. details (optional): An array of specific validation errors or sub-errors, each containing:
  • message: Human-readable description of the specific issue
  • code: Machine-readable code for the specific detail
  • property: The field or parameter that caused the error
  • suggestion: A suggested correct value (when available)
hint (optional): Additional guidance on how to resolve the error.

​
HTTP Status Codes

The SeamlessOS API uses standard HTTP status codes to indicate the general category of error:
Status CodeDescription
400Bad Request - Invalid request syntax or validation errors
401Unauthorized - Missing or invalid authentication credentials
403Forbidden - Valid credentials but insufficient permissions
404Not Found - The requested resource does not exist
409Conflict - Request conflicts with current state (e.g., duplicate idempotency key with different data)
429Too Many Requests - Rate limit exceeded
500Internal Server Error - An unexpected error occurred on our side