Errors
What a failed request returns, and how to handle it.
A request that fails answers with an HTTP error status and a JSON body that says what went wrong. Use code in
your own logic: it stays the same, while message is written for people and may change.
{
"status": 400,
"code": "invalid",
"message": "Some fields are invalid.",
"fields": {
"phone": { "code": "invalid", "message": "Only mobile numbers in Tanzania work here, and this one is from Kenya." }
},
"requestId": "req_..."
}fields appears when the request's data wasn't valid, with a message for each field. Every response, failed or
not, has the same request ID in its X-Request-Id header. Include it when you contact us.
Common codes
| Status | Code | What it means |
|---|---|---|
| 400 | invalid | Some data isn't valid; see fields. |
| 401 | unauthenticated | No token was sent. |
| 401 | invalid_token | The token is wrong, expired or revoked. |
| 403 | missing_permission | The service account doesn't have the permission this request needs. |
| 403 | not_for_service_accounts | This endpoint is only for people signed in to Goomzo. |
| 404 | not_found | The customer, segment or message doesn't exist. |
| 400 | invalid_idempotency_key | The Idempotency-Key is empty, too long or has spaces. |
| 409 | not_cancellable | The message or broadcast has already started sending. |
| 409 | idempotency_key_in_use | A request with this key is still being answered. Retry shortly. |
| 422 | insufficient_sms | There aren't enough SMS to send it. Buy SMS. |
| 422 | idempotency_key_reused | This key was used for a different request. Use a new key. |
| 429 | rate_limited | Too many requests. Wait Retry-After seconds. Rate limits. |
| 500 | internal | Something went wrong on our side. Try again later. |
Token errors
The token endpoint, /v1/oauth/token, answers in the OAuth format instead, with status 400:
{ "error": "invalid_grant", "error_description": "..." }error is invalid_request, unsupported_grant_type or invalid_grant.