Developer documentation

Every error, from authentication to validation to balance, uses the same response envelope. Branch on the stable error_code, never on the localized message: one HTTP status can have several causes. errors is always an object, and data carries the values you need to act, such as amounts and limits.

Error catalog

Evaluation order

Checks run in a fixed order and the first failure is returned, so you always get the most fundamental problem first.

1. Authentication and IP allowlist: 401 or 403 ip_not_allowed.
2. Rate limit: 429 rate_limited.
3. Unknown resource: an {id} in the path that does not exist or belongs to another account returns 404 not_found.
4. Idempotency: a stored response is replayed, or 409.
5. Service switch and service access: 503 service_unavailable, 403 service_disabled or 403 service_restricted.
6. Scope: 403 insufficient_scope.
7. Validation: 422 validation_error, with every field error at once.
8. Content check: 422 content_rejected. The response never says which words matched. If a normal, harmless message is rejected, contact support.
9. Wallet and balance, checked under the wallet lock: 403 wallet_inactive or 402 insufficient_balance.

A request that fails validation never reaches your wallet, so a 402 always means the payload is valid and only the balance is short.

Validation errors

Every problem with the request content is a 422 validation_error: invalid numbers, an empty or overlong body, an unapproved sender, too many recipients, an empty group. Errors are keyed by Laravel dot-notation input path (to.1, messages.2.body) and reported all together. Messages count positions from 1, so to.1 reads "Recipient #2".

{
    "success": false,
    "message": "Recipient #2 is not a valid Bangladeshi mobile number (and 2 more errors)",
    "data": null,
    "errors": {
        "to.1": [
            "Recipient #2 is not a valid Bangladeshi mobile number"
        ],
        "to.4": [
            "Recipient #5 is not a valid Bangladeshi mobile number"
        ],
        "body": [
            "The SMS body is 11 parts long; the maximum is 10 parts"
        ]
    },
    "code": 422,
    "error_code": "validation_error",
    "timestamp": "2026-09-26T10:00:00.000000Z"
}

Insufficient balance

Amounts are strings with two decimals, in BDT. Top up at least data.shortfall and retry; retrying with the same Idempotency-Key is safe because error responses are never stored.

{
    "success": false,
    "message": "Your wallet balance is too low for this request",
    "data": {
        "required": "3.24",
        "available": "1.00",
        "shortfall": "2.24",
        "currency": "BDT"
    },
    "errors": {
        "balance": [
            "This request costs 3.24 BDT but your wallet balance is 1.00 BDT"
        ]
    },
    "code": 402,
    "error_code": "insufficient_balance",
    "timestamp": "2026-09-26T10:00:00.000000Z"
}

Authentication

{
    "success": false,
    "message": "The API key is invalid",
    "data": null,
    "errors": {
        "authorization": [
            "The API key is invalid"
        ]
    },
    "code": 401,
    "error_code": "invalid_api_key",
    "timestamp": "2026-09-26T10:00:00.000000Z"
}

Rate limit

{
    "success": false,
    "message": "Too many requests, retry after 12 seconds",
    "data": {
        "limit": 30,
        "retry_after": 12
    },
    "errors": {
        "rate_limit": [
            "Too many requests, retry after 12 seconds"
        ]
    },
    "code": 429,
    "error_code": "rate_limited",
    "timestamp": "2026-09-26T10:00:00.000000Z"
}