Error response shape

When a request fails, the API returns HTTP 400 Bad Request with a JSON body like this:

{
  "request_id": "e23080fd-8b63-460e-83bd-cf5d2c1497b6",
  "error_code": 3,
  "error": "Message Template does not exist."
}

request_id — a unique identifier for this API request. Quote it when contacting support so engineers can trace the exact request.
error_code — a short integer that identifies the error class within the endpoint family.
error — a human-readable description you can log or surface to developers.

Rate limiting is the only common deviation from HTTP 400 — sustained bursts past the rate limit return HTTP 429 Too Many Requests instead.

Codes are scoped per endpoint family

The numeric error_code is scoped to the API family (WhatsApp, SMS, Telegram, Viber). The same code can map to different errors across families — for example, 6 means “deprecated API key” on the WhatsApp API but “deprecated API key” is 5 on the SMS API.

Always branch on the name when handling errors in code, not on the numeric code alone. Use the numeric code as a shorthand inside a single endpoint family only.

Errors by name

Below, every error name used by the Octopods API. The column headings (WA, Int, SMS, VBM, TG) indicate which endpoint family uses the error and under which numeric code.

Name	WA	Int	SMS	VBM	TG	What it means
`ARGUMENT_MISSING`	1	1	1	1	1	A required parameter is missing from the URL or request body. The `error` text tells you which one.
`TYPE_MISMATCH`	2	2	—	2	4	A parameter was sent in the wrong shape — for example, an array where an object was expected.
`EMPTY_BODY`	—	—	2	—	2	The message text is empty or whitespace-only.
`TEMPLATE_NOT_EXIST`	3	—	—	3	—	No accepted template matches the ID in the URL for the current API key’s workspace/channel.
`VARIABLES_SIZE`	4	—	—	4	—	The number of supplied variables does not match the template’s placeholders. The `error` text gives the expected count.
`PHONE_INVALID`	5	5	3	5	—	The destination phone number is not valid E.164.
`USER_INVALID`	—	—	—	—	3	The Telegram user ID cannot be resolved to a conversation on this channel.
`DEPRECATED_API_KEY`	6	6	5	6	6	The API key has been rotated or revoked. Fetch the current key from Octopods and update your integration.
`WHATSAPP_ERROR`	7	7	—	—	—	WhatsApp rejected the send. The `error` text carries WhatsApp’s reason (for example, the 24-hour window has closed).
`INVALID_HEADER`	8	8	—	8	—	A media header was missing a required field, had the wrong media type, or the media URL could not be fetched.
`LEGACY_VARIABLES_TYPE`	9	—	—	—	—	A flat array was passed for a template whose variables are not body-only. Use the object shape with header/body/footer/buttons.
`INVALID_STATUS`	10	—	—	—	—	The `status` query parameter on list templates was not one of the allowed values.
`SMS_ERROR`	—	—	4	—	—	The SMS provider rejected the send, or an optional parameter like `open_intercom_conversation` had an invalid value.
`VBM_ERROR`	—	—	—	7	—	Viber rejected the send. The `error` text carries the reason.
`TELEGRAM_ERROR`	—	—	—	—	5	Telegram rejected the send (for example, the recipient blocked your bot).

Column key: WA = WhatsApp template endpoint, Int = WhatsApp interactive endpoint, SMS = SMS endpoint, VBM = Viber endpoint, TG = Telegram endpoint.

Resolving ARGUMENT_MISSING

The error text always tells you which parameter is missing. Common cases:

Missing destination_phone on any send endpoint — add the recipient number in E.164.
Missing message_variables when the template has placeholders — check the template’s component shape via the list endpoint.
Missing header_attachment_url (WhatsApp) or header_image_url (Viber) when the template has a media header.

Resolving DEPRECATED_API_KEY

API keys can be rotated or revoked in your workspace settings. When an integration breaks after working fine, this is usually the cause:

Open Octopods → Settings → API Keys.
Copy the current key.
Update your integration’s stored credential.
Redeploy.

Resolving PHONE_INVALID

Octopods validates phone numbers against Phonelib’s E.164 rules. If you’re seeing this error:

Make sure the number starts with + and the country code (e.g. +15551234567, not 5551234567).
Strip spaces, dashes, and parentheses before sending.
For test accounts, some WhatsApp test numbers are accepted by WhatsApp but rejected as “impossible” by Phonelib — use a real, reachable number to test.

Resolving VARIABLES_SIZE

The error text tells you how many variables the template expects. Compare that to the template_components array returned by the list templates endpoint — each placeholder is a {{1}}, {{2}}, etc. inside a component’s text.

If your template’s variables are only in the body, you can send a flat array. Otherwise you must send an object with one array per section (header, body, footer, buttons).

Resolving LEGACY_VARIABLES_TYPE

You sent a flat array for a WhatsApp template that has variables in the header, footer, or URL buttons. Switch to the object shape:

{
  "destination_phone": "+15551234567",
  "message_variables": {
    "header": ["Jane"],
    "body":   ["ORD-9876", "April 28"],
    "footer": [],
    "buttons": ["https://example.com/track/ORD-9876"]
  }
}

Empty sections still need their key present with an empty array.

Resolving INVALID_HEADER

The media URL must be:

Publicly reachable (no authentication, no firewall rules blocking the sender).
The correct type — an image URL for an image header, a video URL for a video header, and so on.
Under the size limit WhatsApp enforces for the given media type.

Resolving WHATSAPP_ERROR, VBM_ERROR, TELEGRAM_ERROR, SMS_ERROR

These wrap the underlying provider’s rejection. Read the error text — it contains the provider’s reason verbatim. Typical causes:

WhatsApp: the 24-hour messaging window has closed for interactive messages, the template was deactivated, or the recipient blocked your number.
Viber: the recipient is not a Viber user (the template’s SMS fallback, if configured, handles this automatically).
Telegram: the recipient has blocked your bot, or the bot was removed from a group.
SMS: the carrier rejected the message, the sender is not approved for the destination country, or the open_intercom_conversation parameter was malformed.

Rate limiting

When you exceed a rate limit the API returns HTTP 429 Too Many Requests and temporarily blocks the API key for a short cool-down window. The response body includes the timestamp when requests will be accepted again. Slow your send cadence and retry after the cool-down — retrying sooner keeps the block in place.

What to include in a support request

When reporting a suspected API bug to Octopods support, include:

The request_id from the failing response (or several, if the issue is intermittent).
The endpoint and HTTP method you called.
The full request body with any secrets redacted.
The exact error response returned.

That is enough to trace the request end-to-end.

API Error Reference