Skip to main content
The Chirp API uses a consistent error format across all endpoints. Every error response follows the same structure, making it easy to handle errors programmatically regardless of which endpoint you are calling.

​
The Error Object

When an API request fails, the response body contains an error object with the following structure:
Error response
{
  "error": {
    "type": "provider_error",
    "code": "message_undeliverable",
    "message": "Unable to deliver message. The recipient may have blocked your number or is not available on WhatsApp.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#message_undeliverable",
    "param": null,
    "provider": {
      "source": "meta",
      "code": 131026,
      "message": "Unable to deliver message",
      "fbtrace_id": "A9PT_GrZ5LIImkA8UdH--jZ"
    }
  }
}

​
Attributes

AttributeTypeAlways presentDescription
typestringYesThe category of error. One of invalid_request_error, authentication_error, provider_error, or api_error.
messagestringYesA human-readable description of the error. Safe to display to end users.
codestringNoA machine-readable error code for programmatic handling. Only present for errors that benefit from branching logic. See Error Codes.
doc_urlstringNoA URL to the documentation page for this specific error code.
paramstringNoThe request parameter that caused the error (e.g., "from", "to[0]"). Present for validation errors.
providerobjectNoUpstream provider error details. Only present when the error originates from Meta or Telnyx.
provider.sourcestring—The provider that returned the error: "meta" or "telnyx".
provider.codenumber or string—The provider’s native error code.
provider.messagestring—The provider’s error message.
provider.fbtrace_idstring—Meta’s trace ID. Include this when contacting Meta support.

​
Error Types

Every error has a type that tells you the category of the problem. The HTTP status code tells you the status; the type tells you what kind of problem occurred.
TypeDescriptionTypical HTTP Codes
invalid_request_errorThe request has invalid parameters, missing fields, or bad formatting.400, 404, 409
authentication_errorThe API key is missing, invalid, or does not have the required permissions.401, 403
provider_errorMeta or Telnyx returned an error. The request was valid, but the operation failed at the provider level.402, 424
api_errorSomething went wrong on Chirp’s end. These are rare and typically transient.500, 502, 503

​
invalid_request_error

Returned when the request itself is malformed or references something that does not exist. Check the param field to identify which parameter caused the issue.
Validation error
{
  "error": {
    "type": "invalid_request_error",
    "message": "The \"from\" field is required.",
    "param": "from"
  }
}
Invalid phone number
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone_number",
    "message": "The phone number \"+1abc\" is not in E.164 format. Expected format: +[country code][number].",
    "param": "from",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#invalid_phone_number"
  }
}

​
authentication_error

Returned when there is a problem with the API key. No code is needed because the type and HTTP status are sufficient.
Authentication error
{
  "error": {
    "type": "authentication_error",
    "message": "Missing Authorization header. Expected: Bearer <api_key>"
  }
}

​
provider_error

Returned when the request was valid but the operation failed at Meta or Telnyx. The provider object contains the raw error from the upstream API. This is the most common error type when sending messages.
Provider error
{
  "error": {
    "type": "provider_error",
    "code": "conversation_window_expired",
    "message": "More than 24 hours since the recipient last replied. Send a template message to re-open the conversation.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#conversation_window_expired",
    "provider": {
      "source": "meta",
      "code": 131047,
      "message": "Re-engagement message",
      "fbtrace_id": "BxYZ_abc123def456"
    }
  }
}

​
api_error

Returned when something goes wrong on Chirp’s end. These errors are rare and typically resolve on their own. Safe to retry with exponential backoff.
API error
{
  "error": {
    "type": "api_error",
    "message": "An unexpected error occurred. Please try again later."
  }
}

​
HTTP Status Codes

The Chirp API uses specific HTTP status codes to indicate the nature of the error:
CodeNameDescription
200OKThe request succeeded.
201CreatedA new resource was created.
400Bad RequestInvalid parameters, missing fields, or bad formatting.
401UnauthorizedNo valid API key was provided.
402Request FailedThe request was valid, but the operation failed (e.g., message could not be delivered).
403ForbiddenThe API key does not have the required permissions.
404Not FoundThe requested resource does not exist.
409ConflictThe request conflicts with the current state (e.g., duplicate resource).
424Failed DependencyAn external provider (Meta or Telnyx) is unavailable or returned an unrecoverable error.
429Too Many RequestsRate limit exceeded. See Rate Limits.
500Server ErrorSomething went wrong on Chirp’s end.
402 vs 400: A 400 means your request was malformed. A 402 means your request was valid, but the operation failed downstream (e.g., the message could not be delivered). This distinction helps you separate input errors from delivery failures.
424 vs 500: A 424 means an external provider (Meta or Telnyx) failed. A 500 means Chirp’s own systems had an issue. This tells you whether the problem is on Chirp’s side or the provider’s side.

​
Provider Errors

When errors originate from Meta (WhatsApp) or Telnyx (SMS/MMS), the provider object contains the raw error details from the upstream API. Chirp maps these provider errors to standardized Chirp error codes so you can handle them consistently. The provider object is useful for:
  • Debugging — The provider’s native error code and message give you additional context.
  • Meta support tickets — Include the fbtrace_id when contacting Meta support about WhatsApp issues.
  • Detailed logging — Log the full provider object for your operations team.
For a complete mapping of provider error codes, see:

​
Next Steps

Error Codes

Complete reference of all error codes with causes and solutions

Handling Errors

Learn how to handle errors in your application