Amarseba API
Developer documentation
সেন্টারসমূহ
Response envelope
Every response from every endpoint, success or error, uses one JSON contract, so your client needs a single parser.
Success
{
"success": true,
"message": "SMS queued for delivery",
"data": { },
"code": 202,
"timestamp": "2026-09-26T10:00:00.000000Z"
}Error
{
"success": false,
"message": "Human-readable summary, localized",
"data": null,
"errors": { "field": ["message"] },
"code": 422,
"error_code": "validation_error",
"timestamp": "2026-09-26T10:00:00.000000Z"
}Success and error share the same top-level keys. Errors add errors and error_code.
Fields
| Field | Meaning |
|---|---|
success | true for 2xx responses, false for every error. |
message | A localized, human-readable summary. For validation it is the first message plus "(and N more errors)". Show it to people; never branch on it. |
data | The payload on success. On errors it is null or an object with the machine-readable values you need to act, such as amounts, limits and retry timing. |
errors | Errors only. Always an object, {} when empty and never a list, mapping a key to an array of messages (Laravel MessageBag shape). Validation uses input paths such as to.3; other errors use one fixed key from the error catalog. |
code | The HTTP status, identical to the response status. |
error_code | Errors only. A stable machine code. Branch on this. |
timestamp | ISO 8601 in UTC. |
Conventions
- Money is a string with two decimals, such as
"0.54", and the currency is always BDT. - Timestamps are ISO 8601 in UTC.
- Resources use prefixed public IDs:
bat_,msg_,grp_,cnt_andkey_. - A resource that belongs to another account returns
404 not_found, exactly like one that does not exist.
Response language
Responses are in English by default. Send Accept-Language: bn to get message and errors in Bangla. Every response states its language in Content-Language. error_code, enum values, field names, numbers and timestamps are the same in both languages, so branch on those, never on message.
curl https://e-amarseba.com/api/v1/wallet/balance \
-H "Authorization: Bearer $AMARSEBA_API_KEY" \
-H "Accept-Language: bn"Handling responses
const result = await response.json();
if (!result.success) {
switch (result.error_code) {
case "insufficient_balance":
return notifyTopUp(result.data.shortfall);
case "rate_limited":
return retryAfter(result.data.retry_after);
case "validation_error":
return showFieldErrors(result.errors);
default:
throw new Error(result.message);
}
}