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. |
| 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.