Error Codes

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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