Errors

The EZ Texting API uses standard HTTP response codes to indicate whether an operation succeeded or failed. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.

Error Response Format

When an error occurs, the API returns a structured JSON response with details about what went wrong:

{
  "status": 400,
  "title": "Malformed Request",
  "detail": "The request you made was malformed",
  "errors": [
    {
      "title": "Sorting Failure",
      "message": "The sort direction query string is required but was missing"
    }
  ]
}

HTTP Status Codes

For rate limit details, see the Rate Limits guide.

Common EZ Texting Error Scenarios

Beyond standard HTTP status codes, certain API errors are specific to EZ Texting operations. Understanding these common scenarios helps you diagnose and resolve issues quickly.

Invalid Phone Number Format

Error Response:

{
  "status": 400,
  "title": "Invalid Phone Number",
  "detail": "The phone number provided is not in a valid format",
  "errors": [
    {
      "title": "Validation Error",
      "message": "Phone number must be 11 digits (E.164 format)"
    }
  ]
}

What causes it: Phone numbers must be provided as 11-digit strings without special characters or spaces. EZ Texting expects E.164 format: a 1-digit country code plus 10-digit number (e.g., 12015551234 for a US number).

How to fix it: Strip non-numeric characters from phone numbers before sending. Validate that the number is exactly 11 digits. If dealing with international numbers, ensure they include the correct country code.

Insufficient Credits

Error Response:

{
  "status": 400,
  "title": "Insufficient Credits",
  "detail": "Your account does not have enough credits to send this message",
  "errors": [
    {
      "title": "Credit Check Failed",
      "message": "Required: 2 credits. Available: 0 credits"
    }
  ]
}

What causes it: Sending messages consumes credits. SMS costs 1 credit per message, MMS costs more depending on file size. If your account balance drops to zero before the request completes, the message fails.

How to fix it: Check your credit balance using GET /v1/account/credits before sending. Purchase more credits via the dashboard or API. For bulk operations, implement a balance check beforehand or catch this error and queue messages for retry after credits are added.

Opted-Out Recipient

Error Response:

{
  "status": 403,
  "title": "Contact Opted Out",
  "detail": "Cannot send a message to this contact",
  "errors": [
    {
      "title": "Opt-Out Violation",
      "message": "Phone number 12015551234 has opted out of messaging"
    }
  ]
}

What causes it: Contacts who have replied "STOP" or been marked as opted-out cannot receive marketing messages. Sending to an opted-out number violates regulations and account policies.

How to fix it: Check the contact's opt-out status before sending. Use GET /v1/contacts/{phoneNumber} to verify their status. Remove opted-out contacts from your mailing lists. Only transactional messages (e.g., 2FA codes, order confirmations) may bypass this restriction in some cases, but best practice is to honor opt-outs universally.

Expired or Invalid Token

Error Response:

{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Your access token has expired or is invalid",
  "errors": [
    {
      "title": "Authentication Failed",
      "message": "Token expired at 2026-04-15T14:30:00Z"
    }
  ]
}

What causes it: OAuth2 access tokens expire after 90 minutes. If a token is revoked or the credentials are invalid, the API rejects all requests using that token.

How to fix it: Use the refresh token to obtain a new access token by calling POST /v1/tokens/refresh. If using HTTP Basic Auth, verify your username and password are correct. For OAuth2 flows, implement automatic token refresh before expiration rather than waiting for failures.

Rate Limit Exceeded

Error Response:

{
  "status": 429,
  "title": "Too Many Requests",
  "detail": "You have exceeded the rate limit",
  "errors": [
    {
      "title": "Rate Limit",
      "message": "Limit of 200 requests per minute exceeded"
    }
  ]
}

Headers:
X-Rate-Limit-Retry-After-Milliseconds: 1500

What causes it: The API enforces a default rate limit of 200 requests per minute. Exceeding this limit returns a 429 status.

How to fix it: Implement exponential backoff with the retry duration from the X-Rate-Limit-Retry-After-Milliseconds header. Space requests evenly across your per-minute budget. Use batch endpoints (e.g., /v1/contacts/batch) to reduce the number of API calls. Cache frequently accessed data like contact groups or keywords.

Best Practices for Error Handling in Production

Robust error handling ensures your application remains stable and responsive even when the API encounters issues.

Retry Logic

Logging and Monitoring

Log all error responses with sufficient context for debugging:

• Request details: HTTP method, path, query parameters, and request body (excluding sensitive data)
• Response details: Status code, response body, and response headers
• Timing: Request timestamp and duration
• Context: User or contact ID being operated on, batch size for bulk operations

Aggregate error logs to identify patterns (e.g., a surge in 401 errors suggests token refresh failures, while 429 errors suggest rate-limiting issues).

User Communication

When operations fail, provide clear feedback to end users without exposing API internals:

• 4xx errors: "There was a problem with your request. Please check the data and try again." (Example: invalid phone number, insufficient credits)
• 5xx errors: "We encountered a temporary issue. Your request is being retried automatically. Please try again if the problem persists."
• Rate limits: "You are sending too many requests. Please slow down and try again in a moment."