Error catalogue

Every error response from the API uses the PaymentGatewayError envelope with a stable four-digit error_code. This page is the full catalogue. Branch on error_code, never on message.

The leading digit groups the cause:

10xx — Authentication
11xx — Validation
12xx — Business logic
13xx — Security
14xx — System
15xx — Carrier / SMS processor

10xx Authentication

Credentials. Never auto-retry — these need human intervention or a fresh credential.

Code	Symbol	Cause	Fix
`1001`	`INVALID_APP_KEY`	The `app-key` value is unknown, malformed, or revoked.	Check the header value matches what’s in the portal. Re-generate if lost.
`1002`	`APP_KEY_MISSING`	No `app-key` header was sent.	Add `app-key: <your_key>` to the request.
`1003`	`APP_NOT_ALLOWED`	The key is valid but the caller isn’t on the allow-list (IP CIDR mismatch).	Add the source IP to the API key’s allow-list.
`1004`	`APP_SUSPENDED`	The key is in `SUSPENDED` state.	Contact your Bloonio account manager. Do not retry.
`1005`	`APP_EXPIRED`	The key’s hard expiry passed.	Regenerate.

11xx Validation

Bad request shape or content. Fix on your side and don’t retry the same payload.

Code	Symbol	Cause	Fix
`1101`	`INVALID_RECIPIENTS`	`to` is empty, too long, or contains non-string values.	`to` is required, max 1 000 entries, every entry must be a string.
`1102`	`INVALID_MESSAGE`	`message` is empty or > 1 600 characters.	Trim or split.
`1103`	`INVALID_SENDER_ID`	`sender_id` has illegal characters or exceeds 11 chars.	A–Z, 0–9, ≤11 chars.
`1104`	`INVALID_PHONE_NUMBER`	An entry in `to` doesn’t match `^\+?\d{1,15}$`.	Format as E.164 (`+CCNNNNN…`). The `details` array shows which entries failed.
`1105`	`INVALID_SENDING_TYPE`	`sending_type` not in `{immediate, scheduled, recurring}`.	Use one of the three values.
`1106`	`INVALID_SCHEDULED_DATE`	An entry in `scheduled_dates` is malformed or in the past.	Use `YYYY-MM-DD` for date, `HH:mm` for time, both in merchant timezone, both ≥ now.
`1107`	`INVALID_RECURRING_SCHEDULE`	The `recurring_schedule` object has missing fields or out-of-range values.	See Sending types for the schema.
`1108`	`INVALID_CALLBACK_URL`	`callback_url` is not a valid HTTPS URL.	Must be `https://…`.
`1109`	`MISSING_REQUIRED_FIELD`	A required field is missing for the chosen `sending_type`.	See `details` for the field name.
`1110`	`INVALID_FIELD_FORMAT`	Generic validation failure. The `details` array has field-level breakdown.	Read `details`, fix each entry.

12xx Business logic

The request was well-formed but the business state forbids it.

Code	Symbol	Cause	Fix
`1201`	`RECIPIENT_LIMIT_EXCEEDED`	More than 1 000 recipients in one call.	Split into batches. See Send an instant SMS.
`1202`	`INSUFFICIENT_BALANCE`	Your balance is below the projected `total_cost`.	Top up via the Bloonio dashboard. Retry with smaller batch or after top-up.
`1203`	`RECURRING_LIMIT_EXCEEDED`	The recurring schedule would generate more than 5 000 SMS.	Shorten `end_date`, reduce `times`, or fewer recipients.
`1204`	`MESSAGE_NOT_FOUND`	`message_id` doesn’t exist, belongs to another merchant, or was purged after 90 days.	Verify the ID is yours.
`1205`	`OPERATION_NOT_ALLOWED`	Trying to `cancel`/`pause`/`resume` a message that isn’t scheduled or recurring (or is already in a terminal state).	Check the current `status` via `GET /status`.

13xx Security

Rate-limiting, blocked IPs, anti-abuse.

Code	Symbol	Cause	Fix
`1301`	`RATE_LIMIT_EXCEEDED`	Per-bucket limit hit.	Honour `Retry-After`. See Rate limits.
`1302`	`SUSPICIOUS_ACTIVITY`	Anti-abuse heuristics flagged the request.	Contact support if legitimate.
`1303`	`IP_BLOCKED`	Source IP on a deny-list.	Use a different network or appeal to ops.
`1304`	`INVALID_WEBHOOK_AUTH`	Webhook receiver returned `401` repeatedly.	Check Basic auth config matches the API key configuration.
`1305`	`REQUEST_TOO_LARGE`	Request body over the 1 MB limit.	Reduce payload size — fewer recipients per call.

14xx System

Server-side issues. Most are transient and retryable: true.

Code	Symbol	Cause	Fix
`1401`	`INTERNAL_SERVER_ERROR`	Unhandled exception inside the gateway.	Retry with backoff. If persistent, contact support with `request_id`.
`1402`	`SERVICE_UNAVAILABLE`	Gateway is in maintenance or overloaded.	Retry after `retry_after`.
`1403`	`DATABASE_ERROR`	Storage layer failure.	Retry.
`1404`	`EXTERNAL_API_ERROR`	Upstream dependency (carrier connector, balance service) errored.	Retry.
`1405`	`TIMEOUT_ERROR`	Internal timeout.	Retry.

15xx Carrier / SMS processor

Failures from the carrier connector or the underlying SMSC.

Code	Symbol	Cause	Fix
`1501`	`CARRIER_UNAVAILABLE`	No carrier connector is available for the destination country.	Contact support.
`1502`	`SMS_REJECTED_BY_CARRIER`	The SMSC rejected the message (typically: invalid number, sender ID not registered for the destination).	Check `details` for the carrier reason.
`1503`	`SMS_TIMEOUT`	No delivery receipt within 24 h.	Treated as `failed`; no further retry.
`1504`	`SMS_BLOCKED`	The destination handset blocked the sender or the message was flagged as spam.	Reach out via another channel; review your sender ID and message content.
`1505`	`INSUFFICIENT_CARRIER_QUOTA`	The carrier connector itself has insufficient quota with the SMSC (operator-level).	Bloonio-side issue; contact support. Will be `retryable: true` for transient cases.