Skip to content

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. message is meant for people and may change.
  • Retry only when retryable is true, and with the same Idempotency-Key.
  • Give the request_id to support.

This table is generated from the API code on every release, so every code the API can return is listed here.

General

HTTPcodeWhenWhat to doRetry
400idempotency_key_requiredPOST, PATCH or DELETE without Idempotency-KeySend the headerNo
400invalid_cursorThe cursor was changed or belongs to another listUse the previous page's next_cursor as isNo
400invalid_idempotency_keyKey longer than 255 characters or with characters outside visible ASCIIUse a UUIDNo
400invalid_jsonThe body is not JSONFix the requestNo
400invalid_requestA field is invalid or missing (details.fields)Fix the requestNo
401api_key_revokedThe key was revokedCreate another keyNo
401authentication_requiredNo Authorization: Bearer headerSend the keyNo
401invalid_api_keyMalformed or unknown keyCheck the key and the environment (pf_live_ in production)No
403insufficient_scopeThe key lacks the route's scope (details.required_scope). For webhooks, subscribing to or reading an event type also requires its module's read scopeCreate a key with that scopeNo
403plan_upgrade_requiredThe workspace plan has no API access (Free, Try)Subscribe to a paid plan; the same key starts working againNo
403workspace_archivedThe key's workspace was archivedUse a key from another workspaceNo
404lead_not_foundThe lead_id is not a lead of this workspaceCheck the idNo
404not_foundThe resource does not exist in this workspaceCheck the idNo
404route_not_foundThe route does not existCheck the path and the versionNo
405method_not_allowedMethod not accepted (see the Allow header)Use the right methodNo
409idempotency_conflictThe Idempotency-Key was already used with a different bodyGenerate a new key for the new operationNo
409request_in_progressThe request with this key is still runningTry again shortlySometimes (check retryable)
409request_outcome_unknownThe request with this key finished without a confirmed outcomeCheck the resource before retrying with another keyNo
413payload_too_largeBody over 1 MB, or file over 16 MBReduce the sizeNo
415unsupported_media_typeBody without Content-Type: application/jsonSend the headerNo
429rate_limitedLimit reached (Retry-After). Includes the webhook test, retry and creation limits (details.bucket)Wait for the time in Retry-AfterYes
500internal_errorUnexpected errorFor writes, check the resource before repeatingYes
503temporarily_unavailableTemporarily unavailableTry again with the same Idempotency-KeyYes

WhatsApp and files

HTTPcodeWhenWhat to doRetry
402insufficient_creditsNot enough credits to sendTop up creditsNo
404file_not_foundThe media.file_id is not a file of this workspaceUpload it again with POST /v1/filesNo
404sender_not_foundfrom is not a line of this workspaceUse an id from GET /v1/whatsapp/sendersNo
404template_not_foundNo template with that nameCheck GET /v1/whatsapp/templatesNo
409contact_blockedContact closed, lost, left the company, or from your own companyTalk to the team in PreflowNo
409contact_pausedThe contact is paused until a date (details.until)Try after that dateNo
409privacy_suppressedThe contact asked not to receive messagesDo not sendNo
409sender_unavailableThe line is not ready (disconnected, paused for quality or being set up)Use another line or fix it in PreflowNo
422file_not_uploadedThe bytes were not sent to the upload URLPUT the file before sending the messageNo
422invalid_phonePhone number not in E.164Use +5511999998888No
422media_type_not_allowedFile type not accepted (details.allowed)Convert the fileNo
422provider_rejectedWhatsApp rejected the message; nothing was chargedCheck the number and the contentNo
422send_refusedPreflow refused the send for another reasonContact support with the request_idNo
422sender_requiredNo from and no default line on the keySend from or set the default lineNo
422template_not_approvedThe template is not approved for the line's providerWait for approvalNo
422template_unavailable_on_senderA WhatsApp Business app (phone) line cannot send templatesUse another lineNo
422template_variables_invalidVariables are missing (details.missing)Fill in all of themNo
422whatsapp_window_closedText or media outside the 24-hour window (details.last_inbound_at)Use an approved templateNo

Leads, accounts, cadences and meetings

HTTPcodeWhenWhat to doRetry
403integration_actor_unavailableWhoever created the key can no longer enroll leads in the workspaceAsk an admin for a new keyNo
404cadence_not_foundThe cadence is not from this workspace or was archivedUse an id from GET /v1/cadencesNo
404lead_mergedThe lead was merged into another (details.merged_into)Use the lead in details.merged_into from now onNo
409cadence_born_cancelledEvery step would be created cancelled (details.reason)Check the reason; nothing was enrolledNo
409cadence_enrollment_refusedAny other enrollment refusalCheck the lead and try again with another Idempotency-KeyNo
409cadence_no_tasks_createdNo step can be created (details.skipped_channels)Complete the lead's contact data (email, phone) or use another cadenceNo
409cadence_operator_unavailableThe 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 ownerNo
409external_id_in_progressAnother request is creating the lead for this external_id right nowTry again shortly; the response returns the lead the other request createdSometimes (check retryable)
409lead_already_in_cadenceThe lead is already in this cadenceNothing to doNo
409lead_archivedThe lead is archivedReopen the lead in PreflowNo
409lead_engagement_pausedThe lead replied recently (details.until)Try after details.untilNo
409lead_in_active_conversationThe lead is in an ongoing conversationTry after the conversation endsNo
409lead_not_eligible_for_cadenceThe 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_untilNo
422cadence_has_no_stepsThe cadence has no stepsUse another cadenceNo
422lead_suppressedThe contact asked not to be contacted (privacy). Also refuses conversions from POST /v1/inbound-submissions, before anything is recordedDo not create the lead againNo

Conversions (POST /v1/inbound-submissions)

HTTPcodeWhenWhat to doRetry
409submission_id_conflictThe submission_id was already used with different contentUse a new submission_id for a new conversionNo
409submission_in_progressAnother request is recording the same conversion right nowTry again shortlySometimes (check retryable)
422answers_invalidWith 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 formNo
422campaign_not_foundcampaign is not the slug of a campaign of this workspace (or it is archived)Check the campaign slugNo
422form_not_foundform_id is not a published form of this workspaceCheck the form idNo
422funnel_not_foundfunnel_id is not an active funnel of this workspaceUse an id from GET /v1/funnelsNo

Webhooks

HTTPcodeWhenWhat to doRetry
400invalid_webhook_urlURL that is not https://, has a user and password, or is longer than 2048 charactersFix the URLNo
400unknown_event_typeEvent not in the catalogCheck GET /v1/event-typesNo
400webhook_url_not_allowedInternal, private, metadata or Preflow addressUse a public URL of your systemNo
409webhook_delivery_already_succeededRetry of a delivery that already succeededNothing to do: the event already arrivedNo
409webhook_delivery_in_progressThe delivery is being sent right nowTry again shortlyNo
409webhook_endpoint_limit_reachedThe workspace already has 10 endpointsDelete an endpointNo
409webhook_endpoint_not_activeTest or retry on an endpoint that is disabled or paused by the planTurn the endpoint back onNo
409webhook_rotation_in_progressThe secret was rotated less than 24 h agoWait for the previous one to expireNo