Errors

The Txtly API uses standard HTTP status codes and returns a consistent JSON error body with a descriptive message.

Error Format

Error responses contain an error field with a human-readable message (or, for a few machine-checkable cases, an uppercase error code plus a separate message):

{
  "error": "'to' is required and must contain at least one recipient"
}

Some errors include extra context fields alongside error — for example batch endpoints add the failing index, rate-limit errors add limit and remaining, and suppression errors add suppressed_emails.

Status Codes

Here are the status codes the API uses and what they mean:

Status	Description
`400`	Request validation failed (missing/invalid fields, unverified domain, inactive sender, suppressed recipient). Check the error message.
`401`	Missing or invalid API key.
`403`	The action is not permitted — e.g. `RECIPIENT_OPTED_OUT` when an SMS targets an opted-out number.
`404`	The requested resource was not found.
`409`	The request conflicts with existing data (e.g., duplicate sender ID).
`422`	The request is well-formed but cannot be processed — e.g. `UNSUPPORTED_DESTINATION_COUNTRY` for SMS.
`429`	A daily limit, spend cap, batch-size limit, or the API request limiter was exceeded. See Rate Limits.
`502`	The upstream messaging provider failed to accept the message. Safe to retry.
`500`	An internal server error occurred. Our team has been notified.

Example Error Responses

Sending an email from an unverified domain:

{
  "error": "Domain 'example.org' is not verified."
}

A batch email failing at index 1:

{
  "error": "Email at index 1 is invalid",
  "index": 1
}

An SMS to an unsupported destination:

{
  "error": "UNSUPPORTED_DESTINATION_COUNTRY",
  "message": "SMS sends to this destination country are not currently supported. Contact support to request coverage."
}

Handling Errors

Always check the status code and error message in your application to handle errors appropriately. For 429 (rate limit) errors, implement exponential backoff before retrying.