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": "Unsupported mobile number." }
},
"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. |
| 400 | invalid_json | The body isn't one valid JSON object, or has a field the endpoint doesn't take. |
| 400 | invalid_cursor | The cursor isn't one a list gave you. Start from the first page. |
| 400 | invalid_limit | limit isn't a whole number from 1. |
| 400 | invalid_status, invalid_channel, invalid_period, invalid_test | A filter has a value the list doesn't know. |
| 400 | invalid_api_version | Goomzo-Version isn't a version of the API. |
| 400 | invalid_idempotency_key | The Idempotency-Key is too long or has spaces. |
| 401 | unauthenticated | No secret was sent. |
| 401 | invalid_token | The secret is wrong, expired or revoked. |
| 403 | missing_permission | The API key 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. |
| 404 | route_not_found | There's no such endpoint. Check the path. |
| 405 | method_not_allowed | The endpoint doesn't take this method. |
| 409 | not_cancellable | The message or broadcast has already started sending. |
| 409 | name_in_use | Another segment already has this name. |
| 409 | segment_limit | You already have 500 segments, or this would take you past them. |
| 409 | segment_fills_itself | The segment is automatic: its rules decide who's in it. |
| 409 | segment_in_use | Another segment's rules use this segment, so it can't be deleted yet. |
| 409 | rule_segment_limit | You already have 50 automatic segments. |
| 409 | channel_unavailable | Sending by this channel isn't set up yet. |
| 409 | too_many_endpoints | You already have 10 webhook endpoints. |
| 409 | endpoint_disabled | The webhook endpoint is turned off, so it can't be sent events. |
| 409 | idempotency_key_in_use | A request with this key is still being answered. Retry shortly. |
| 413 | body_too_large | The request body is too large. |
| 422 | insufficient_sms | There aren't enough SMS to send it; needed and available say how many. SMS bundles. |
| 422 | too_many_to_export | More than 50,000 customers match. Search or filter to export fewer. |
| 422 | rules_too_slow | A segment's rules took too long to work out. Use fewer or simpler conditions. |
| 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.
Last updated