Errors
Every error has the same format:
{ "error": { "code": "insufficient_scope", "message": "The key does not have the scope required for this route.", "request_id": "req_6f1c2b0e8a7d4c3b9e2f1a0d5c4b3a29", "retryable": false, "details": { "required_scope": "whatsapp:send" } }}- Branch on
code, which is stable.messageis meant for people and may change. - Retry only when
retryableistrue, and with the sameIdempotency-Key. - Give the
request_idto support.
Catalog
Section titled “Catalog”This table is generated from the API code on every release, so every code the API can return is listed here.
General
| HTTP | code | When | What to do | Retry |
|---|---|---|---|---|
| 400 | idempotency_key_required | POST, PATCH or DELETE without Idempotency-Key | Send the header | No |
| 400 | invalid_cursor | The cursor was changed or belongs to another list | Use the previous page's next_cursor as is | No |
| 400 | invalid_idempotency_key | Key longer than 255 characters or with characters outside visible ASCII | Use a UUID | No |
| 400 | invalid_json | The body is not JSON | Fix the request | No |
| 400 | invalid_request | A field is invalid or missing (details.fields) | Fix the request | No |
| 401 | api_key_revoked | The key was revoked | Create another key | No |
| 401 | authentication_required | No Authorization: Bearer header | Send the key | No |
| 401 | invalid_api_key | Malformed or unknown key | Check the key and the environment (pf_live_ in production) | No |
| 403 | insufficient_scope | The key lacks the route's scope (details.required_scope). For webhooks, subscribing to or reading an event type also requires its module's read scope | Create a key with that scope | No |
| 403 | plan_upgrade_required | The workspace plan has no API access (Free, Try) | Subscribe to a paid plan; the same key starts working again | No |
| 403 | workspace_archived | The key's workspace was archived | Use a key from another workspace | No |
| 404 | lead_not_found | The lead_id is not a lead of this workspace | Check the id | No |
| 404 | not_found | The resource does not exist in this workspace | Check the id | No |
| 404 | route_not_found | The route does not exist | Check the path and the version | No |
| 405 | method_not_allowed | Method not accepted (see the Allow header) | Use the right method | No |
| 409 | idempotency_conflict | The Idempotency-Key was already used with a different body | Generate a new key for the new operation | No |
| 409 | request_in_progress | The request with this key is still running | Try again shortly | Sometimes (check retryable) |
| 409 | request_outcome_unknown | The request with this key finished without a confirmed outcome | Check the resource before retrying with another key | No |
| 413 | payload_too_large | Body over 1 MB, or file over 16 MB | Reduce the size | No |
| 415 | unsupported_media_type | Body without Content-Type: application/json | Send the header | No |
| 429 | rate_limited | Limit reached (Retry-After). Includes the webhook test, retry and creation limits (details.bucket) | Wait for the time in Retry-After | Yes |
| 500 | internal_error | Unexpected error | For writes, check the resource before repeating | Yes |
| 503 | temporarily_unavailable | Temporarily unavailable | Try again with the same Idempotency-Key | Yes |
WhatsApp and files
| HTTP | code | When | What to do | Retry |
|---|---|---|---|---|
| 402 | insufficient_credits | Not enough credits to send | Top up credits | No |
| 404 | file_not_found | The media.file_id is not a file of this workspace | Upload it again with POST /v1/files | No |
| 404 | sender_not_found | from is not a line of this workspace | Use an id from GET /v1/whatsapp/senders | No |
| 404 | template_not_found | No template with that name | Check GET /v1/whatsapp/templates | No |
| 409 | contact_blocked | Contact closed, lost, left the company, or from your own company | Talk to the team in Preflow | No |
| 409 | contact_paused | The contact is paused until a date (details.until) | Try after that date | No |
| 409 | privacy_suppressed | The contact asked not to receive messages | Do not send | No |
| 409 | sender_unavailable | The line is not ready (disconnected, paused for quality or being set up) | Use another line or fix it in Preflow | No |
| 422 | file_not_uploaded | The bytes were not sent to the upload URL | PUT the file before sending the message | No |
| 422 | invalid_phone | Phone number not in E.164 | Use +5511999998888 | No |
| 422 | media_type_not_allowed | File type not accepted (details.allowed) | Convert the file | No |
| 422 | provider_rejected | WhatsApp rejected the message; nothing was charged | Check the number and the content | No |
| 422 | send_refused | Preflow refused the send for another reason | Contact support with the request_id | No |
| 422 | sender_required | No from and no default line on the key | Send from or set the default line | No |
| 422 | template_not_approved | The template is not approved for the line's provider | Wait for approval | No |
| 422 | template_unavailable_on_sender | A WhatsApp Business app (phone) line cannot send templates | Use another line | No |
| 422 | template_variables_invalid | Variables are missing (details.missing) | Fill in all of them | No |
| 422 | whatsapp_window_closed | Text or media outside the 24-hour window (details.last_inbound_at) | Use an approved template | No |
Leads, accounts, cadences and meetings
| HTTP | code | When | What to do | Retry |
|---|---|---|---|---|
| 403 | integration_actor_unavailable | Whoever created the key can no longer enroll leads in the workspace | Ask an admin for a new key | No |
| 404 | cadence_not_found | The cadence is not from this workspace or was archived | Use an id from GET /v1/cadences | No |
| 404 | lead_merged | The lead was merged into another (details.merged_into) | Use the lead in details.merged_into from now on | No |
| 409 | cadence_born_cancelled | Every step would be created cancelled (details.reason) | Check the reason; nothing was enrolled | No |
| 409 | cadence_enrollment_refused | Any other enrollment refusal | Check the lead and try again with another Idempotency-Key | No |
| 409 | cadence_no_tasks_created | No step can be created (details.skipped_channels) | Complete the lead's contact data (email, phone) or use another cadence | No |
| 409 | cadence_operator_unavailable | The lead's account has no one to run the cadence (details.reason: missing_cadence_operator, cadence_operator_conflicts_with_account_owner, cadence_operator_not_eligible, human_account_owner_not_eligible or ai_cadence_requires_human_account_owner) | Set the account's pre-sales owner | No |
| 409 | external_id_in_progress | Another request is creating the lead for this external_id right now | Try again shortly; the response returns the lead the other request created | Sometimes (check retryable) |
| 409 | lead_already_in_cadence | The lead is already in this cadence | Nothing to do | No |
| 409 | lead_archived | The lead is archived | Reopen the lead in Preflow | No |
| 409 | lead_engagement_paused | The lead replied recently (details.until) | Try after details.until | No |
| 409 | lead_in_active_conversation | The lead is in an ongoing conversation | Try after the conversation ends | No |
| 409 | lead_not_eligible_for_cadence | The lead cannot enter a cadence now (details.reason: lead_do_not_contact_until, lead_passed_meeting_stage, lost_cooldown, lost_reprospect_not_eligible, status_not_appendable, meeting_reprospect_not_eligible, not_eligible) | Check the reason; lost_cooldown includes details.cooldown_until | No |
| 422 | cadence_has_no_steps | The cadence has no steps | Use another cadence | No |
| 422 | lead_suppressed | The contact asked not to be contacted (privacy). Also refuses conversions from POST /v1/inbound-submissions, before anything is recorded | Do not create the lead again | No |
Conversions (POST /v1/inbound-submissions)
| HTTP | code | When | What to do | Retry |
|---|---|---|---|---|
| 409 | submission_id_conflict | The submission_id was already used with different content | Use a new submission_id for a new conversion | No |
| 409 | submission_in_progress | Another request is recording the same conversion right now | Try again shortly | Sometimes (check retryable) |
| 422 | answers_invalid | With form_id: an answer for a field that does not exist, outside the options, or a required field left empty (details.fields) | Match the answers to the form | No |
| 422 | campaign_not_found | campaign is not the slug of a campaign of this workspace (or it is archived) | Check the campaign slug | No |
| 422 | form_not_found | form_id is not a published form of this workspace | Check the form id | No |
| 422 | funnel_not_found | funnel_id is not an active funnel of this workspace | Use an id from GET /v1/funnels | No |
Webhooks
| HTTP | code | When | What to do | Retry |
|---|---|---|---|---|
| 400 | invalid_webhook_url | URL that is not https://, has a user and password, or is longer than 2048 characters | Fix the URL | No |
| 400 | unknown_event_type | Event not in the catalog | Check GET /v1/event-types | No |
| 400 | webhook_url_not_allowed | Internal, private, metadata or Preflow address | Use a public URL of your system | No |
| 409 | webhook_delivery_already_succeeded | Retry of a delivery that already succeeded | Nothing to do: the event already arrived | No |
| 409 | webhook_delivery_in_progress | The delivery is being sent right now | Try again shortly | No |
| 409 | webhook_endpoint_limit_reached | The workspace already has 10 endpoints | Delete an endpoint | No |
| 409 | webhook_endpoint_not_active | Test or retry on an endpoint that is disabled or paused by the plan | Turn the endpoint back on | No |
| 409 | webhook_rotation_in_progress | The secret was rotated less than 24 h ago | Wait for the previous one to expire | No |