Errors and troubleshooting
Look up Headless error codes by category, and the expiry limits that apply.
Formerly V1.2
Headless was called the V1.2 REST API. This page was at /authentication/v1-2/errors; old links still work. The API and its field names are unchanged.
Error Reference
Headless errors use status, code, and message. Middleware-generated errors may also include retryable, retryAfter, cooldownSeconds, and details; the response fields depend on the endpoint and error path.
{
"status": "error",
"code": "ERROR_CODE",
"message": "Human-readable description",
"retryable": true,
"retryAfter": "2026-03-25T12:01:00.000Z",
"cooldownSeconds": 3600,
"details": {}
}
Expiration fields
| Limit | Value |
|---|---|
| Challenge expiry | Scales with difficulty — 90s at difficulty 2–3, 120s at 4, 240s at 5, 300s at 6. The default difficulty is 3, so most integrations get 90 seconds. Read expiresAt from the challenge response; see Challenge expiry scales with difficulty. |
| Captcha token expiry | 2 minutes |
| Transaction expiry | 3 minutes. Use data.expiresAt from the send response when deciding whether to request a new OTP. |
Headless has no resend and no request signing
The core OTP flow is three endpoints — /challenge, /send and /verify. There is no resend endpoint: to give a user another code, run the flow again from /challenge. (Headless also mounts a separate passkey ceremony under /api/v1.2/transactions/passkey, gated independently of the OTP flow — see Passkeys.) Headless also has no request-signing scheme — your requests are authenticated by APIKey plus the PoW and Turnstile proofs, not by a signature you compute. (Request signing on outbound webhooks is separate and covered in Webhook Callbacks; the usk_ signing scheme belongs to One-way messaging (Utilities), and screen-level signing to Gateway.)
Authentication Errors
| Status | Code | Cause and Solution |
|---|---|---|
| 400 | MISSING_REQUIRED_FIELDS | APIKey and pipelineID are required for the challenge request; transactionReqID and otp are required for verification. |
| 401 | INVALID_API_KEY | API key is invalid or does not match any account. Verify in your dashboard. |
| 403 | API_KEY_SCOPE_DENIED | The key is limited to some integrations and this integration is not one of them. Use a key whose scope covers it. Returned by /challenge, /send and the passkey auth-options call. |
| 503 | API_KEY_INDEX_UNAVAILABLE | The key could not be checked right now. The response carries retryable: true: try again shortly. Returned by /challenge, /send and the passkey auth-options call. |
Integration and Configuration Errors
| Status | Code | Cause and Solution |
|---|---|---|
| 403 | PIPELINE_OWNERSHIP_MISMATCH | The integration belongs to a different account. Use an integration owned by the account identified by APIKey. |
| 403 | INVALID_API_VERSION | The integration is not configured for Headless. |
| 403 | PIPELINE_INACTIVE | The integration is off. Select Turn on in Setup on its Basics tab. |
| 403 | UTILITY_PIPELINE_ON_OTP_ENDPOINT | The selected integration is a One-way messaging integration. Use the One-way messaging API instead. |
| 404 | PIPELINE_NOT_FOUND | The pipelineID does not identify an existing integration. |
| 500 | PIPELINE_NOT_LOADED | The server could not load integration data for a security check. Retry the request. |
Channel Choice Errors
Returned only when you pass channel. The three validation codes are lower-case, unlike the rest
of this reference — that is what the API actually returns. Validation runs before the
availability check, so an unrecognised channel value is reported as invalid_channel even on a
integration where channel choice is switched off.
| Status | Code | Cause and Solution |
|---|---|---|
| 400 | invalid_channel | channel was not one of whatsapp, telegram, sms — or you passed it without a verificationAddress.phoneNumber. Sending channel: null counts as passing it: omit the field entirely to use the integration's normal routing. |
| 400 | channel_choice_not_enabled | Not available for this account and integration. Covers the account entitlement, the integration switch, the platform-wide switch, legacy (non-granular) pricing and accounts not billed per message. Check the integration switch in Dashboard > Integrations first; if that is on, ask Akedly. |
| 400 | channel_not_eligible | A valid channel, but not one this integration sends on. The response carries eligibleChannels, in the integration's own configured order — offer the user those. The order reflects your integration configuration, not any ranking by us. |
| 422 | pre_send_failure | The channel was refused before anything was sent, so nothing was spent — today this means a telegram number that is not reachable on Telegram. Offer the user another channel. |
| 500 | ACTIVATION_FAILED | The send failed for any other reason. Because you named a channel explicitly, no fallback was attempted. Retry, or send again without channel to use the integration's normal routing. |
OTP Template Errors
Returned with HTTP 400 when the request or the integration default selects an OTP template that cannot be used. Nothing is sent or billed. Remedies are in the OTP templates guide.
| Status | Code | Cause |
|---|---|---|
| 400 | TEMPLATE_UNKNOWN | The template id is malformed, not found, or not owned by the account. |
| 400 | TEMPLATE_ARCHIVED | The template was archived. |
| 400 | TEMPLATE_WABA_REQUIRED | The account has no active own WABA, or its token cannot be read. |
| 400 | TEMPLATE_WABA_CHANGED | The template belongs to a previous WABA. |
| 400 | TEMPLATE_NOT_APPROVED | The OTP language has no approved variant. |
| 400 | TEMPLATE_REJECTED | Meta rejected the OTP language variant. |
| 400 | TEMPLATE_VARIABLE_MISSING | A required variable has no request value or stored default. |
| 400 | TEMPLATE_VARIABLE_INVALID | A variable name or value is invalid, or the template object contains an unsupported key. |
Challenge and Captcha Errors
| Status | Code | Cause and Solution |
|---|---|---|
| 400 | POW_SOLUTION_MISSING | The request omitted the PoW solution while PoW was required. Solve the current challenge and send its challengeToken and nonce. |
| 400 | POW_INVALID_TOKEN, POW_INVALID_SIGNATURE, POW_PIPELINE_MISMATCH, POW_INVALID_SOLUTION | The submitted PoW proof is invalid or bound to another integration. Fetch a new challenge and solve it for this integration. |
| 409 | POW_CHALLENGE_REPLAYED, POW_DIFFICULTY_STALE | The proof was already consumed or was minted below the current difficulty. Fetch a new challenge and retry. |
| 410 | POW_CHALLENGE_EXPIRED | The PoW challenge has expired. The TTL scales with difficulty (90s at the default difficulty 3, up to 300s at difficulty 6) — do not assume 5 minutes. Request a new challenge from Step 1. |
| 500 | POW_VERIFICATION_FAILED, POW_DIFFICULTY_CALCULATION_FAILED | The server could not complete a PoW operation. Retry the request. |
| 400 | TURNSTILE_TOKEN_MISSING | Turnstile is enabled but no token was provided. Obtain a token before sending. |
| 403 | TURNSTILE_VERIFICATION_FAILED | Cloudflare rejected the Turnstile token. Obtain a fresh token and retry. |
| 500 | TURNSTILE_SECRET_KEY_MISSING | The integration's Turnstile secret is not configured. Contact the integration owner. |
| 502 | TURNSTILE_API_ERROR | Turnstile's API returned an error. Retry the request. |
| 504 | TURNSTILE_VALIDATION_TIMEOUT | Turnstile validation timed out. Retry the request. |
Rate Limiting Errors
Each 429 response includes retryAfter (ISO timestamp) and cooldownSeconds (number) so you can back off precisely. Headless emits these explicit codes: RATE_LIMIT_PHONENUMBER_PERMINUTE, RATE_LIMIT_PHONENUMBER_PERHOUR, RATE_LIMIT_PHONENUMBER_PERDAY, RATE_LIMIT_ENDUSERIP_PERMINUTE, RATE_LIMIT_ENDUSERIP_PERHOUR, RATE_LIMIT_ENDUSERIP_PERDAY, RATE_LIMIT_PIPELINE_PERMINUTE, RATE_LIMIT_PIPELINE_PERHOUR, RATE_LIMIT_PIPELINE_PERDAY, and, on /send, IDENTITY_TEMPORARILY_BLOCKED. Headless also emits one fixed code, RATE_LIMIT_PIPELINE_ABUSE, described in the last row.
| Status | Code | Cause and Solution |
|---|---|---|
| 429 | RATE_LIMIT_PHONENUMBER_PERMINUTE, RATE_LIMIT_PHONENUMBER_PERHOUR, RATE_LIMIT_PHONENUMBER_PERDAY | The same phone number has requested too many OTPs in this window. Wait for retryAfter before retrying. |
| 429 | RATE_LIMIT_ENDUSERIP_PERMINUTE, RATE_LIMIT_ENDUSERIP_PERHOUR, RATE_LIMIT_ENDUSERIP_PERDAY | Too many requests from the same end-user IP, as sent in the required x-end-user-ip header. If many different users hit this limit, check that your backend forwards each user's own IP, not your server's, load balancer's or proxy's. |
| 429 | RATE_LIMIT_PIPELINE_PERMINUTE, RATE_LIMIT_PIPELINE_PERHOUR, RATE_LIMIT_PIPELINE_PERDAY | Integration-wide cap reached across all end users. Consider raising the integration rate limits in the dashboard. |
| 429 | IDENTITY_TEMPORARILY_BLOCKED | Returned by /send. The identity is under a zero-verify ban. That ban can happen when an identity keeps receiving codes and none is recorded as entered correctly: send every code your user enters to the verify call. retryable is false even though a schedule is supplied — the ban is terminal until it expires, so honour retryAfter (the ban expiry) and cooldownSeconds (the remaining wait) rather than branching on retryable. |
| 429 | RATE_LIMIT_PIPELINE_ABUSE | Akedly refused the request to protect the integration from excess traffic and gives no further reason. The body carries retryAfter (60 seconds after the response), cooldownSeconds: 60 and no details. No OTP is sent, no transaction is created and nothing is billed, and test pairs are never refused with this code. The proof was spent, so request a new challenge and solve it when challengeRequired is true, and obtain a fresh Turnstile token when Turnstile is required, before you retry. Wait at least cooldownSeconds; a retry is judged again and can be refused again. |
Circuit Breaker Errors
The circuit breaker is an integration-level flood guard: when an integration's traffic looks like an attack it trips, and every send is refused for a cooldown rather than burning your OTP budget. Its thresholds and cooldown are configured on the integration.
| Status | Code | Cause and Solution |
|---|---|---|
| 503 | CIRCUIT_BREAKER_OPEN | Integration circuit breaker is open due to flood detection. Wait for cooldownSeconds. |
| 503 | CIRCUIT_BREAKER_TRIGGERED | Integration suspended due to sustained high traffic. Automatic recovery after cooldown. |
Transaction and Verification Errors
| Status | Code | Cause and Solution |
|---|---|---|
| 400 | MISSING_REQUIRED_FIELDS | Required fields are missing from the request. For send, provide APIKey and pipelineID; for verify, provide transactionReqID and otp. |
| 400 | MISSING_VERIFICATION_ADDRESS | The send request did not include a verificationAddress with a phoneNumber or email. |
| 500 | TRANSACTION_NOT_FOUND | The transaction created for the send request could not be retrieved. Retry the request. |
| 410 | TRANSACTION_EXPIRED | Transaction expired. Use the expiresAt value returned by send and create a new transaction when it has passed. |
| 403 | INVALID_OTP | OTP entered by user does not match. Prompt them to re-enter. |
| 409 | ALREADY_VERIFIED | The transaction request was already verified. Do not submit the same request again. |
| 429 | MAX_ATTEMPTS_EXCEEDED | 10th wrong OTP on this transaction. The transaction is force-expired — create a new one; further attempts return TRANSACTION_EXPIRED. |
| 500 | SEND_OTP_FAILED | The Headless send operation failed outside the handled transaction paths. Retry the request. |
| Propagated status (default 500) | ACTIVATION_FAILED | The transaction was created but could not be activated. Retry according to the returned status. |
| 402 | BILLING_FAILED | Billing failed while verifying the OTP. Resolve the billing issue before retrying. |
| 500 | VERIFY_OTP_FAILED | The verify operation failed outside the handled verification outcomes. Retry the request. |
| Propagated from transaction creation (default 400) | TRANSACTION_CREATION_FAILED | The underlying transaction could not be created. The response preserves its status and, when the creator supplies one, its own code, so read code before this one. For example DESTINATION_COUNTRY_BLOCKED (403) when the destination is not allowed or SYSTEM_MANAGED_PIPELINE_FORBIDDEN (404) for an integration reserved for platform operations. |
Challenge-generation errors
The challenge endpoint returns 500 for an unhandled challenge-generation failure. The PoW service
may identify the failure as POW_CHALLENGE_GENERATION_FAILED; the controller fallback is
CHALLENGE_GENERATION_FAILED.
| Status | Code | Cause and Solution |
|---|---|---|
| 500 | CHALLENGE_GENERATION_FAILED, POW_CHALLENGE_GENERATION_FAILED | The server could not create a PoW challenge. Retry the challenge request. |
Validation Errors
| Status | Code | Cause and Solution |
|---|---|---|
| 400 | INVALID_OTP_LANGUAGE | Invalid otpLanguage; see accepted values. Before retrying, fetch and solve a new challenge when proof-of-work is enabled and obtain a fresh Turnstile token when required. |
| 400 | VALIDATION_ERROR | Request body failed validation. Check the details field for specific issues. |
| 413 | PAYLOAD_TOO_LARGE | Request body exceeds size limit. |
Server Errors
| Status | Code | Cause and Solution |
|---|---|---|
| 500 | INTERNAL_SERVER_ERROR | Unexpected server error. Retry the request. If persistent, contact support at support@akedly.io. |
