Error Codes

Chirp uses error codes to help you programmatically handle specific error conditions. Not all errors include a code — only errors that benefit from programmatic branching. For errors without a code, use type and message to understand the issue. For a full description of the error format, see Errors.

Quick Reference

Code	Type	HTTP	Description
`message_undeliverable`	`provider_error`	402	Message could not be delivered to recipient
`conversation_window_expired`	`provider_error`	402	24-hour WhatsApp conversation window has expired
`recipient_not_on_whatsapp`	`provider_error`	402	Recipient is not registered on WhatsApp
`phone_number_not_assigned`	`invalid_request_error`	400	Phone number is not assigned to your app
`unsupported_message_type`	`invalid_request_error`	400	Message type not supported by the channel
`media_too_large`	`invalid_request_error`	400	Media file exceeds the platform size limit
`invalid_phone_number`	`invalid_request_error`	400	Phone number is not in E.164 format
`template_not_found`	`invalid_request_error`	404	Template does not exist or is not approved
`template_parameter_mismatch`	`invalid_request_error`	400	Template variable count or format is wrong
`groups_not_eligible`	`provider_error`	402	Phone number is not eligible for the Groups API
`account_restricted`	`provider_error`	403	WhatsApp account has been restricted by Meta
`display_name_not_approved`	`provider_error`	402	Phone number display name is pending Meta approval
`whatsapp_not_configured`	`invalid_request_error`	400	No WhatsApp Business Profile configured for this app
`meta_api_error`	`api_error`	424	Unexpected error from Meta Graph API
`meta_api_unavailable`	`api_error`	424	Meta API is temporarily unavailable
`telnyx_api_error`	`api_error`	424	Unexpected error from Telnyx API
`telnyx_api_unavailable`	`api_error`	424	Telnyx API is temporarily unavailable
`rate_limit_exceeded`	`invalid_request_error`	429	Too many requests
`whatsapp_rate_limited`	`provider_error`	429	WhatsApp messaging rate limit reached by Meta
`resource_already_exists`	`invalid_request_error`	409	A resource with this identifier already exists
`test_app_required`	`authentication_error`	403	Endpoint is only available to test apps

Messaging Errors

message_undeliverable


Type	`provider_error`
HTTP Status	402
Description	The message could not be delivered to the recipient.

Common Causes:

The recipient has blocked your business number
The recipient’s phone is turned off or unreachable
The recipient is not available on WhatsApp
Meta’s ecosystem protection chose not to deliver the message

How to Fix:

Verify the recipient’s phone number is correct and active
Check if the recipient has opted out of receiving messages
Try sending to a different number to verify your setup works

Related Provider Codes:

Provider	Code	Meaning
Meta	131026	Unable to deliver message
Meta	131049	Ecosystem protection
Meta	130472	Experiment participant

Example Response:

message_undeliverable 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",
    "provider": {
      "source": "meta",
      "code": 131026,
      "message": "Unable to deliver message"
    }
  }
}

conversation_window_expired


Type	`provider_error`
HTTP Status	402
Description	The 24-hour WhatsApp conversation window has expired. You must use a template message to re-open the conversation.

Common Causes:

More than 24 hours have passed since the recipient last sent you a message
Attempting to send a free-form message outside the conversation window

How to Fix:

Send a template message to re-open the conversation
Set up webhooks to track when customers message you, so you can respond within 24 hours

Related Provider Codes:

Provider	Code	Meaning
Meta	131047	Re-engagement message

Example Response:

conversation_window_expired response

{
  "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"
    }
  }
}

recipient_not_on_whatsapp


Type	`provider_error`
HTTP Status	402
Description	The recipient phone number is not registered on WhatsApp.

Common Causes:

The phone number does not have WhatsApp installed
The phone number is a landline or VoIP number
The phone number was recently deactivated

How to Fix:

Verify the phone number is correct
Confirm the recipient uses WhatsApp
Consider falling back to SMS for this recipient

Example Response:

recipient_not_on_whatsapp response

{
  "error": {
    "type": "provider_error",
    "code": "recipient_not_on_whatsapp",
    "message": "The recipient phone number is not registered on WhatsApp.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#recipient_not_on_whatsapp"
  }
}

phone_number_not_assigned


Type	`invalid_request_error`
HTTP Status	400
Description	The phone number exists in your organization but is not assigned to the app you are sending from.

Common Causes:

Using a phone number that belongs to a different app
The phone number was recently unassigned from this app
Using a test key with a production phone number

How to Fix:

Assign the phone number to your app in the dashboard
Verify you are using the correct app key
Check phone number assignments via the Phone Numbers API

Example Response:

phone_number_not_assigned response

{
  "error": {
    "type": "invalid_request_error",
    "code": "phone_number_not_assigned",
    "message": "The phone number +15551234567 is not assigned to this app.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#phone_number_not_assigned",
    "param": "from"
  }
}

unsupported_message_type


Type	`invalid_request_error`
HTTP Status	400
Description	The message type is not supported by the channel.

Common Causes:

Sending an interactive message type that is not supported
Using a media type the platform does not accept
Attempting to send a WhatsApp-only message type via SMS

How to Fix:

Check the supported message types for the channel you are using
Verify media types are within platform limits

Related Provider Codes:

Provider	Code	Meaning
Meta	131051	Unsupported message type

Example Response:

unsupported_message_type response

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_message_type",
    "message": "This message type is not supported by WhatsApp.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#unsupported_message_type"
  }
}

media_too_large


Type	`invalid_request_error`
HTTP Status	400
Description	The media file exceeds the platform’s size limit.

Common Causes:

Image exceeds 5 MB (WhatsApp or MMS)
Video exceeds 16 MB (WhatsApp) or 5 MB (MMS)
Document exceeds 100 MB (WhatsApp)

How to Fix:

Compress the media file before sending
Use a lower resolution or bitrate
Check platform media limits for exact size constraints

Example Response:

media_too_large response

{
  "error": {
    "type": "invalid_request_error",
    "code": "media_too_large",
    "message": "The image file exceeds the maximum size of 5 MB for WhatsApp.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#media_too_large",
    "param": "media"
  }
}

invalid_phone_number


Type	`invalid_request_error`
HTTP Status	400
Description	The phone number is not in E.164 format.

Common Causes:

Missing the + prefix
Including spaces, dashes, or parentheses
Invalid country code or number length

How to Fix:

Format the number as +[country code][number] with no spaces or special characters
Example: +14155552671 (US number) or +447911123456 (UK number)

Example Response:

invalid_phone_number response

{
  "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].",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#invalid_phone_number",
    "param": "from"
  }
}

Template Errors

template_not_found


Type	`invalid_request_error`
HTTP Status	404
Description	The template does not exist or has not been approved in the specified language.

Common Causes:

Typo in the template name
The template has not been approved by Meta yet
The template was approved in a different language than the one requested
The template was rejected for policy violations

How to Fix:

Check the template name in the dashboard
Verify the template status is “approved”
Ensure you are requesting the correct language code
See Templates for template management

Related Provider Codes:

Provider	Code	Meaning
Meta	132001	Template does not exist in the specified language
Meta	132007	Template rejected for policy violation

Example Response:

template_not_found response

{
  "error": {
    "type": "invalid_request_error",
    "code": "template_not_found",
    "message": "Template 'order_confirmation' does not exist or hasn't been approved in language 'en_US'.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#template_not_found"
  }
}

template_parameter_mismatch


Type	`invalid_request_error`
HTTP Status	400
Description	The template variable count or format does not match the template definition.

Common Causes:

Sending too many or too few variables for the template
Variables are in the wrong format (e.g., sending a string where a currency object is expected)
Template definition was updated but your code still sends old parameters

How to Fix:

Check the template definition for the exact number and format of variables
Ensure each variable matches the expected type
Re-sync your template data if the template was recently updated

Related Provider Codes:

Provider	Code	Meaning
Meta	132000	Template parameter count mismatch
Meta	132012	Template variable format mismatch

Example Response:

template_parameter_mismatch response

{
  "error": {
    "type": "invalid_request_error",
    "code": "template_parameter_mismatch",
    "message": "Template 'order_confirmation' expects 3 variables but 2 were provided.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#template_parameter_mismatch"
  }
}

Group Errors

groups_not_eligible


Type	`provider_error`
HTTP Status	402
Description	The phone number is not eligible for the WhatsApp Groups API.

Common Causes:

The phone number has not been approved for the Groups API by Meta
The WhatsApp Business Account does not meet the Groups API requirements

How to Fix:

Check with Meta for Groups API eligibility requirements
Ensure your WhatsApp Business Account is in good standing
See WhatsApp Groups for setup instructions

Related Provider Codes:

Provider	Code	Meaning
Meta	131215	Not eligible for Groups API

Example Response:

groups_not_eligible response

{
  "error": {
    "type": "provider_error",
    "code": "groups_not_eligible",
    "message": "This phone number is not eligible to access the Groups API.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#groups_not_eligible",
    "provider": {
      "source": "meta",
      "code": 131215,
      "message": "Groups not eligible"
    }
  }
}

Account Errors

account_restricted


Type	`provider_error`
HTTP Status	403
Description	Your WhatsApp Business Account has been restricted by Meta.

Common Causes:

Policy violations on your WhatsApp Business Account
Billing issues with your Meta account
High spam report rate from recipients
Messaging to restricted countries

How to Fix:

Review Meta’s Commerce Policy and Business Policy
Check your Meta Business Manager for any policy violation notices
Resolve any outstanding billing issues
Appeal the restriction through Meta Business Manager if you believe it was applied in error

Related Provider Codes:

Provider	Code	Meaning
Meta	368	Policy violations
Meta	130497	Country restriction
Meta	131031	Account locked
Meta	131042	Payment issue

Example Response:

This error is automatically enriched with Health Status details when Meta returns it. The additional_info and provider.health_status fields tell you exactly which entity is blocking and what Meta suggests.

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",
      "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."
              }
            ]
          }
        ]
      }
    }
  }
}

display_name_not_approved


Type	`provider_error`
HTTP Status	402
Description	The phone number’s display name is pending Meta approval.

Common Causes:

A new display name was submitted and is still being reviewed
Meta rejected the display name and it reverted to the previous one

How to Fix:

Wait for Meta to approve the display name (typically 24-48 hours)
Check the phone number status in your dashboard
If rejected, submit a new display name that complies with Meta’s naming guidelines

Related Provider Codes:

Provider	Code	Meaning
Meta	131037	Display name not approved

Example Response:

This error is automatically enriched with Health Status details. additional_info carries Meta’s own remediation text (e.g. current review status, approval ETA).

display_name_not_approved response

{
  "error": {
    "type": "provider_error",
    "code": "display_name_not_approved",
    "message": "Phone number display name is pending Meta approval.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#display_name_not_approved",
    "additional_info": [
      "Your display name has not been approved yet. Your message limit will increase after the display name is approved."
    ],
    "provider": {
      "source": "meta",
      "code": 131037,
      "message": "Display name not approved",
      "health_status": {
        "can_send_message": "LIMITED",
        "entities": [
          {
            "entity_type": "PHONE_NUMBER",
            "id": "852850827913949",
            "can_send_message": "LIMITED",
            "additional_info": [
              "Your display name has not been approved yet. Your message limit will increase after the display name is approved."
            ]
          }
        ]
      }
    }
  }
}

whatsapp_not_configured


Type	`invalid_request_error`
HTTP Status	400
Description	No WhatsApp Business Profile is configured for this app.

Common Causes:

Attempting to send a WhatsApp message from an app that has not completed Embedded Signup
The WhatsApp Business Profile was disconnected or deleted

How to Fix:

Complete the Embedded Signup flow to connect a WhatsApp Business Account
Check that a WhatsApp phone number is assigned to your app

Example Response:

whatsapp_not_configured response

{
  "error": {
    "type": "invalid_request_error",
    "code": "whatsapp_not_configured",
    "message": "No WhatsApp Business Profile is configured for this app. Complete the Embedded Signup flow to get started.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#whatsapp_not_configured"
  }
}

Provider Errors

meta_api_error


Type	`api_error`
HTTP Status	424
Description	An unexpected error occurred with the Meta Graph API.

Common Causes:

Meta returned an unrecognized or generic error code
A transient issue with Meta’s infrastructure

How to Fix:

Retry the request with exponential backoff
Check the provider.code and provider.message for additional context
If the issue persists, contact support with the provider.fbtrace_id

Related Provider Codes:

Provider	Code	Meaning
Meta	1	API Unknown
Meta	131000	Unknown error
Meta	135000	Generic error

Example Response:

meta_api_error response

{
  "error": {
    "type": "api_error",
    "code": "meta_api_error",
    "message": "An unknown error occurred with the Meta API.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#meta_api_error",
    "provider": {
      "source": "meta",
      "code": 1,
      "message": "API Unknown",
      "fbtrace_id": "CxYZ_trace123"
    }
  }
}

meta_api_unavailable


Type	`api_error`
HTTP Status	424
Description	Meta’s API is temporarily unavailable.

Common Causes:

Meta is experiencing an outage or degraded performance
The WhatsApp Business Account is in maintenance mode
Temporary service disruption

How to Fix:

Retry the request with exponential backoff
Check Meta’s status page for known outages
If the issue persists for more than 30 minutes, contact support

Related Provider Codes:

Provider	Code	Meaning
Meta	2	API Service
Meta	131016	Service unavailable
Meta	131057	Maintenance mode

Example Response:

meta_api_unavailable response

{
  "error": {
    "type": "api_error",
    "code": "meta_api_unavailable",
    "message": "Meta API is temporarily unavailable. Please try again later.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#meta_api_unavailable",
    "provider": {
      "source": "meta",
      "code": 2,
      "message": "API Service"
    }
  }
}

telnyx_api_error


Type	`api_error`
HTTP Status	424
Description	An unexpected error occurred with the Telnyx API.

Common Causes:

Telnyx returned an unrecognized or generic error
A transient issue with Telnyx’s infrastructure

How to Fix:

Retry the request with exponential backoff
Check the provider.code and provider.message for additional context
If the issue persists, contact support

Example Response:

telnyx_api_error response

{
  "error": {
    "type": "api_error",
    "code": "telnyx_api_error",
    "message": "An unexpected error occurred with the Telnyx API.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#telnyx_api_error",
    "provider": {
      "source": "telnyx",
      "code": "40300",
      "message": "Could not send message"
    }
  }
}

telnyx_api_unavailable


Type	`api_error`
HTTP Status	424
Description	Telnyx’s API is temporarily unavailable.

Common Causes:

Telnyx is experiencing an outage or degraded performance
Temporary service disruption

How to Fix:

Retry the request with exponential backoff
Check Telnyx’s status page for known outages
If the issue persists for more than 30 minutes, contact support

Example Response:

telnyx_api_unavailable response

{
  "error": {
    "type": "api_error",
    "code": "telnyx_api_unavailable",
    "message": "Telnyx API is temporarily unavailable. Please try again later.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#telnyx_api_unavailable",
    "provider": {
      "source": "telnyx",
      "code": "503",
      "message": "Service Unavailable"
    }
  }
}

Rate Limiting Errors

rate_limit_exceeded


Type	`invalid_request_error`
HTTP Status	429
Description	You have sent too many requests in a given time period.

Common Causes:

Exceeding the per-endpoint rate limit
Burst of requests without rate limiting on your end

How to Fix:

Implement exponential backoff (see Handling Errors)
Check the Retry-After header for how long to wait
See Rate Limits for per-endpoint limits

Example Response:

rate_limit_exceeded response

{
  "error": {
    "type": "invalid_request_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 30 seconds.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#rate_limit_exceeded"
  }
}

whatsapp_rate_limited


Type	`provider_error`
HTTP Status	429
Description	Meta’s WhatsApp messaging rate limit has been reached.

Common Causes:

Sending too many WhatsApp messages in a short period
Your WhatsApp Business Account’s messaging tier limit was reached

How to Fix:

Implement exponential backoff
Request a higher messaging tier through Meta Business Manager
Spread messages over a longer time window

Example Response:

whatsapp_rate_limited response

{
  "error": {
    "type": "provider_error",
    "code": "whatsapp_rate_limited",
    "message": "WhatsApp messaging rate limit reached. Please try again later.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#whatsapp_rate_limited",
    "provider": {
      "source": "meta",
      "code": 130429,
      "message": "Rate limit hit"
    }
  }
}

Resource Errors

resource_already_exists


Type	`invalid_request_error`
HTTP Status	409
Description	A resource with this identifier already exists.

Common Causes:

Attempting to create a resource with a slug or name that is already taken
Duplicate webhook registration
Re-submitting a creation request that already succeeded

How to Fix:

Use a different identifier for the new resource
Check if the resource already exists before creating it
If this was a retry, the resource may have been created on the first attempt

Example Response:

resource_already_exists response

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_already_exists",
    "message": "A function with slug 'my-function' already exists.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#resource_already_exists"
  }
}

Playground Errors

test_app_required


Type	`authentication_error`
HTTP Status	403
Description	The endpoint is only available to test apps. The provided API key belongs to a live app.

Common Causes:

Calling a playground endpoint with a live API key (sk_live_app_*)
Using a production app key for testing scenarios

How to Fix:

Use a test API key (sk_test_app_*) for the test app paired with your live app
Switch to your test environment when simulating inbound traffic

Example Response:

test_app_required response

{
  "error": {
    "type": "authentication_error",
    "code": "test_app_required",
    "message": "The playground inbound endpoint is only available for test apps. Use a test API key (sk_test_app_*) to simulate inbound traffic.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#test_app_required"
  }
}

API Reference

Application APIs

Administration APIs

Quick Reference

Messaging Errors

message_undeliverable

conversation_window_expired

recipient_not_on_whatsapp

phone_number_not_assigned

unsupported_message_type

media_too_large

invalid_phone_number

Template Errors

template_not_found

template_parameter_mismatch

Group Errors

groups_not_eligible

Account Errors

account_restricted

display_name_not_approved

whatsapp_not_configured

Provider Errors

meta_api_error

meta_api_unavailable

telnyx_api_error

telnyx_api_unavailable

Rate Limiting Errors

rate_limit_exceeded

whatsapp_rate_limited

Resource Errors

resource_already_exists

Playground Errors

test_app_required

​Quick Reference

​Messaging Errors

​message_undeliverable

​conversation_window_expired

​recipient_not_on_whatsapp

​phone_number_not_assigned

​unsupported_message_type

​media_too_large

​invalid_phone_number

​Template Errors

​template_not_found

​template_parameter_mismatch

​Group Errors

​groups_not_eligible

​Account Errors

​account_restricted

​display_name_not_approved

​whatsapp_not_configured

​Provider Errors

​meta_api_error

​meta_api_unavailable

​telnyx_api_error

​telnyx_api_unavailable

​Rate Limiting Errors

​rate_limit_exceeded

​whatsapp_rate_limited

​Resource Errors

​resource_already_exists

​Playground Errors

​test_app_required

Quick Reference

Messaging Errors

message_undeliverable

conversation_window_expired

recipient_not_on_whatsapp

phone_number_not_assigned

unsupported_message_type

media_too_large

invalid_phone_number

Template Errors

template_not_found

template_parameter_mismatch

Group Errors

groups_not_eligible

Account Errors

account_restricted

display_name_not_approved

whatsapp_not_configured

Provider Errors

meta_api_error

meta_api_unavailable

telnyx_api_error

telnyx_api_unavailable

Rate Limiting Errors

rate_limit_exceeded

whatsapp_rate_limited

Resource Errors

resource_already_exists

Playground Errors

test_app_required