Errors

The Txtly API uses standard HTTP status codes and returns consistent error responses. All errors include a status code, error name, and descriptive message.

Error Format

All error responses follow this format:

{
  "status_code": 400,
  "name": "validation_error",
  "message": "Request validation failed"
}

Error Codes

Here are the possible error codes and their meanings:

Status	Error Name	Description
`400`	`validation_error`	Request validation failed. Check your request parameters.
`401`	`authentication_error`	Missing or invalid API key.
`403`	`authorization_error`	Your API key doesn't have permission for this action.
`404`	`not_found`	The requested resource was not found.
`409`	`conflict`	The request conflicts with existing data (e.g., duplicate email).
`422`	`unprocessable_entity`	The request is well-formed but contains invalid data.
`429`	`rate_limit_exceeded`	Too many requests. Please slow down and retry after some time.
`500`	`internal_error`	An internal server error occurred. Our team has been notified.

Example Error Response

When you try to send an email with missing required fields:

{
  "status_code": 400,
  "name": "validation_error",
  "message": "Validation failed",
  "errors": {
    "to": ["Email address is required"],
    "from": ["Sender email is required"]
  }
}

Handling Errors

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