Error Reference

The Sent API uses standard HTTP status codes and returns detailed error information following the FastEndpoints problem details format.

Error Codes Overview

Error Response Format

All errors follow this standard structure:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred",
  "status": 400,
  "errors": {
    "fieldName": ["Error message"]
  }
}

Common Error Codes

400 Bad Request

Invalid request parameters or business logic errors.

Validation Errors

{
  "status": 400,
  "errors": {
    "phoneNumber": ["Phone number is required"],
    "templateId": ["TemplateId is required"]
  }
}

Invalid Phone Number

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid phone number"
}

Insufficient Balance

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Insufficient balance. Current balance: 0.0050, estimated cost: 0.0200"
}

Template Not Found

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Template not found"
}

Invalid Channel

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid channel: email. Supported channels are: sms, whatsapp"
}

401 Unauthorized

Authentication failures.

Missing Headers

{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Header x-api-key not found"
}

Invalid Credentials

{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Invalid API credentials!"
}

403 Forbidden

Access denied to the requested resource.

{
  "status": 403,
  "title": "Forbidden"
}

404 Not Found

Resource not found.

{
  "status": 404,
  "title": "Not Found"
}

Common scenarios:

• Contact not found (when looking up by ID)
• Template not found for the authenticated customer

429 Too Many Requests

Rate limiting (future implementation).

{
  "status": 429,
  "title": "Too Many Requests",
  "detail": "Rate limit exceeded. Please retry after 60 seconds."
}

500 Internal Server Error

Server-side errors.

{
  "status": 500,
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred"
}

Error Handling Best Practices

1. Implement Retry Logic

• Use exponential backoff for server errors (5xx)
• Don't retry client errors (4xx)
• Set reasonable timeout limits

2. Parse Error Details

• Check for validation errors in the errors field
• Handle specific error messages in the detail field
• Log errors for debugging

3. Handle Specific Error Scenarios

• Monitor balance levels to prevent insufficient balance errors
• Validate inputs before sending requests
• Implement proper error recovery flows

Common Error Scenarios

Phone Number Validation

• Include country code for accurate parsing
• Remove special characters before sending
• Use E.164 format when possible (+1234567890)

Template Errors

• Ensure template is published and approved
• Verify all required parameters are provided
• Check parameter names match exactly

Balance Issues

• Monitor balance levels proactively
• Implement auto-recharge if possible
• Check estimated costs before sending

Contact Lookup

• Use contact ID when available (faster)
• Handle auto-creation for phone lookups
• Don't assume contacts exist

Webhook Error Handling

When providing webhook URLs, ensure your endpoint:

• Responds quickly (< 5 seconds)
• Returns 2xx status codes
• Handles duplicate notifications
• Implements proper error logging