Error Handling

SendAPI uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, authentication failed, etc.).
• Codes in the 5xx range indicate an error with SendAPI's servers (these are rare).

Standard Error Response

When an API request fails, SendAPI returns a JSON object containing an error hash.

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "param": "to",
    "message": "The 'to' field is required to route the message."
  }
}

Error Attributes

Field	Type	Description
type	string	The category of error (invalid_request_error, api_error, authentication_error, rate_limit_error).
code	string	A short string indicating the exact error code. Useful for programmatic parsing.
message	string	A human-readable message providing more details about the error.
param	string?	(Optional) The specific query or body parameter related to the error, if applicable.

HTTP Status Codes Reference

Code	Description
200 - OK	Everything worked as expected.
201 - Created	The resource (like a message or a new configuration) was successfully created.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter or failing validation.
401 - Unauthorized	No valid API key provided. Check your Authorization bearer token.
403 - Forbidden	The API key doesn't have permissions to perform the request (e.g., trying to send an email with an SMS-only scoped key).
404 - Not Found	The requested resource doesn't exist.
409 - Conflict	The request conflicts with another request (e.g., using the same idempotency key for a different payload).
422 - Unprocessable	The parameters were valid, but the request failed computationally (e.g., recipient phone number is physically invalid/disconnected according to the global telecom ledger).
429 - Too Many Requests	Too many requests hit the API too quickly. Back off and retry.
500 - Server Error	Something went wrong on SendAPI's end. (These are rare).