Every request returns 401
Confirm the api.intelliconcierge.dev host, the Bearer scheme, the full key value, its expiry, and whether it was rotated or revoked.
Search for a command to run...
Reliability
JSON errorsAll public API failures use one envelope. Branch first on HTTP status and the stable code, then use message and details for diagnosis.
The optional details object carries structured validation or provider context. Do not parse the human-readable message to drive application logic.
{
"error": {
"code": "unauthorized",
"message": "Missing or malformed API key. Send `Authorization: Bearer ik_...`."
}
}{
"error": {
"code": "bad_request",
"message": "Request validation failed.",
"details": {
"to": ["Enter a valid recipient identifier."]
}
}
}| HTTP | code | Meaning | Retry? |
|---|---|---|---|
| 400 | bad_request | Malformed JSON, invalid fields, or an unsupported channel/type combination. | No |
| 401 | unauthorized | Missing, malformed, expired, revoked, or invalid API key. | No |
| 402 | trial_expired | Trial and grace ended; live sending is paused until a plan is active. | No |
| 403 | forbidden | The key is valid but does not have the required scope. | No |
| 404 | not_found | The client, template, or requested resource does not exist for this partner. | No |
| 409 | conflict | The reference, phone number, or channel account is already connected. | No |
| 422 | unprocessable | The request was understood but rejected by the channel provider. | Usually no |
| 429 | rate_limited | The request window is exhausted. | Yes |
| 500 | internal_error | An unexpected edge error occurred. | Yes |
| 502 | upstream_unavailable | The partner API could not obtain a usable upstream response. | Yes |
These arrive as 400 alongside the generic bad_request cases, so branch on code rather than on the status. None of them are worth retrying unchanged.
| code | Endpoint | Meaning |
|---|---|---|
| channel_type_unsupported | /messages/send | The client's channel does not carry this message type. Instagram takes text, image, video, audio and document; templates, sticker, location, contacts, interactive and reaction are WhatsApp-only. |
| media_link_required | /messages/send | Media was sent to an Instagram client as an uploaded media id. Instagram fetches the file itself, so pass a public HTTPS URL in <type>.link instead. |
| meta_rejected | /messages/send, /messages/send-template | Meta refused the send. The response carries Meta's own code and message — correct the cause before retrying. |
| outside_service_window | /messages/send | The recipient's 24-hour customer service window is closed (no inbound message from them in the last 24 hours). Meta would accept the send and then silently drop delivery (error 131047). Portal and ik_test_ sends are refused with 422; live sends proceed with a warning. Send an approved template, or wait for the customer to message again. |
| template_not_approved | /messages/send-template | The template named by template_ref exists but Meta hasn't approved it (the rejection reason is included when there is one). Poll GET /templates/{ref} until status is APPROVED. |
| missing_parameters | /messages/send-template | The template has placeholders the request didn't fill; the message names them. Related codes from the same family: parameter_count_mismatch, missing_header, missing_button_parameters, missing_cards, missing_card_buttons, empty_parameter and invalid_header_link — see the Messages reference. |
| template_layout_unsupported | /messages/send-template | Authentication templates and copy-code buttons can't be assembled from template_ref — send them as a raw template object. |
| media_type_unsupported | /media | The uploaded file isn't a WhatsApp send media type. Supported: image jpeg/png, video mp4/3gpp, audio aac/mp4/mpeg/amr/ogg, document pdf/Office/txt, sticker webp. |
| media_too_large | /media | The file exceeds WhatsApp's ceiling for its kind — 5 MB images, 16 MB video/audio, 100 MB documents, 500 KB stickers. |
| number_already_connected | /embedded-signup/sessions | That WhatsApp number is already connected, either under one of your client references or through another provider. |
Retry network failures, 429, 500, and 502 with capped exponential backoff and jitter. Honor Retry-After when present. Do not automatically retry validation, authentication, scope, or provider-policy failures without changing the cause.
Avoid duplicate business actions
Confirm the api.intelliconcierge.dev host, the Bearer scheme, the full key value, its expiry, and whether it was rotated or revoked.
Create or rotate a key with the endpoint scope. Client onboarding needs clients:write, reads need clients:read, and sends need messages:send.
That is expected for ik_test_ keys and dry_run: true. A dry-run response includes dry_run: true and does not contact the recipient.
Do not create random retries. Check whether client_ref already resolves. A phone number or Instagram account can also be connected under another reference or provider.
Check the 24-hour reply window, recipient identifier, template approval and language, media URL reachability, and the channel capability matrix.
Run the dashboard simulator, check Delivery Logs, return 2xx within five seconds, and verify the HMAC against the raw body rather than parsed JSON.