Errors

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

Attribute	Type	Always present	Description
`type`	string	Yes	The category of error. One of `invalid_request_error`, `authentication_error`, `provider_error`, or `api_error`.
`message`	string	Yes	A human-readable description of the error. Safe to display to end users.
`code`	string	No	A machine-readable error code for programmatic handling. Only present for errors that benefit from branching logic. See Error Codes.
`doc_url`	string	No	A URL to the documentation page for this specific error code.
`param`	string	No	The request parameter that caused the error (e.g., `"from"`, `"to[0]"`). Present for validation errors.
`provider`	object	No	Upstream provider error details. Only present when the error originates from Meta or Telnyx.
`provider.source`	string	—	The provider that returned the error: `"meta"` or `"telnyx"`.
`provider.code`	number or string	—	The provider’s native error code.
`provider.message`	string	—	The provider’s error message.
`provider.fbtrace_id`	string	—	Meta’s trace ID. Include this when contacting Meta support.
`provider.health_status`	object	—	Meta Health Status payload. Present when Chirp enriched the error via Meta’s Health Status API (see Health Status Enrichment).
`additional_info`	string[]	No	Human-readable remediation hints. Ordered: BLOCKED entities’ suggested solutions first, then LIMITED entities’ additional info. Populated alongside `provider.health_status`.

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.

Type	Description	Typical HTTP Codes
`invalid_request_error`	The request has invalid parameters, missing fields, or bad formatting.	400, 404, 409
`authentication_error`	The API key is missing, invalid, or does not have the required permissions.	401, 403
`provider_error`	Meta or Telnyx returned an error. The request was valid, but the operation failed at the provider level.	402, 424
`api_error`	Something 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:

Code	Name	Description
200	OK	The request succeeded.
201	Created	A new resource was created.
400	Bad Request	Invalid parameters, missing fields, or bad formatting.
401	Unauthorized	No valid API key was provided.
402	Request Failed	The request was valid, but the operation failed (e.g., message could not be delivered).
403	Forbidden	The API key does not have the required permissions.
404	Not Found	The requested resource does not exist.
409	Conflict	The request conflicts with the current state (e.g., duplicate resource).
424	Failed Dependency	An external provider (Meta or Telnyx) is unavailable or returned an unrecoverable error.
429	Too Many Requests	Rate limit exceeded. See Rate Limits.
500	Server Error	Something 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:

WhatsApp Error Codes for Meta error code mappings
SMS Error Codes for Telnyx error code mappings

Health Status Enrichment (WhatsApp)

For certain vague Meta errors — account_restricted and display_name_not_approved — Chirp automatically calls Meta’s Health Status API and attaches the specific blocked entity and Meta’s suggested remediation to the error response. When enrichment runs, you get two extra fields:

additional_info — a flat string[] with Meta’s possible_solution text, ordered with the most critical hints first.
provider.health_status — the full entity tree (phone number, WABA, business portfolio, app, template) with per-entity status and error details.

Enriched account_restricted response

{
  "error": {
    "type": "provider_error",
    "code": "account_restricted",
    "message": "Account has been locked due to policy violation.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#account_restricted",
    "additional_info": [
      "Appeal via Business Manager."
    ],
    "provider": {
      "source": "meta",
      "code": 131031,
      "message": "Account has been locked",
      "fbtrace_id": "BxYZ_abc123def456",
      "health_status": {
        "can_send_message": "BLOCKED",
        "entities": [
          {
            "entity_type": "PHONE_NUMBER",
            "id": "852850827913949",
            "can_send_message": "BLOCKED",
            "errors": [
              {
                "error_code": 131031,
                "error_description": "Account has been locked",
                "possible_solution": "Appeal via Business Manager."
              }
            ]
          },
          {
            "entity_type": "WABA",
            "id": "1472866130489042",
            "can_send_message": "AVAILABLE"
          }
        ]
      }
    }
  }
}

Enrichment is best-effort. If Chirp’s follow-up call to Meta fails, you still get the base error — additional_info and provider.health_status will simply be absent. Never branch on whether they exist; treat them as hints on top of error.code.

See Health Status Enrichment in the WhatsApp error guide for the full list of enriched codes, entity types, and failure-webhook behavior.

API Reference

Application APIs

Administration APIs

The Error Object

Attributes

Error Types

invalid_request_error

authentication_error

provider_error

api_error

HTTP Status Codes

Provider Errors

Health Status Enrichment (WhatsApp)

Next Steps

Error Codes

Handling Errors

​The Error Object

​Attributes

​Error Types

​invalid_request_error

​authentication_error

​provider_error

​api_error

​HTTP Status Codes

​Provider Errors

​Health Status Enrichment (WhatsApp)

​Next Steps

Error Codes

Handling Errors

The Error Object

Attributes

Error Types

invalid_request_error

authentication_error

provider_error

api_error

HTTP Status Codes

Provider Errors

Health Status Enrichment (WhatsApp)

Next Steps