--- title: "Errors" description: "What a failed request returns, and how to handle it." url: "https://docs.goomzo.africa/docs/developers/errors" docs_index: /llms.txt lastUpdated: 2026-11-12 section: "Overview" related: - /docs/developers - /docs/developers/authentication - /docs/developers/idempotency - /docs/developers/rate-limits --- > For an index of all documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt). Any page is also available as Markdown by adding .md to its URL. # 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. ```json { "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](https://docs.goomzo.africa/docs/help/segments?utm_source=llms&utm_medium=ai#automatic-segments): 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](https://docs.goomzo.africa/docs/developers/webhooks?utm_source=llms&utm_medium=ai) 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](https://docs.goomzo.africa/docs/help/sms-bundles?utm_source=llms&utm_medium=ai). | | 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](https://docs.goomzo.africa/docs/developers/idempotency?utm_source=llms&utm_medium=ai). | | 429 | `rate_limited` | Too many requests. Wait `Retry-After` seconds. [Rate limits](https://docs.goomzo.africa/docs/developers/rate-limits?utm_source=llms&utm_medium=ai). | | 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: ```json { "error": "invalid_grant", "error_description": "..." } ``` `error` is `invalid_request`, `unsupported_grant_type` or `invalid_grant`. --- For an index of all available documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt)