Errors

Understanding error responses and how to handle them in the SeamlessOS API.

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 Code	Description
400	Bad Request - Invalid request syntax or validation errors
401	Unauthorized - Missing or invalid authentication credentials
403	Forbidden - Valid credentials but insufficient permissions
404	Not Found - The requested resource does not exist
409	Conflict - Request conflicts with current state (e.g., duplicate idempotency key with different data)
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - An unexpected error occurred on our side