Error codes
Every error code the BWEZE API returns, its HTTP status, what it means, and whether a retry can help.
Every API error looks like this:
{ "error": { "code": "token_expired", "message": "...", "docs": "https://docs.bweze.com/errors/token_expired" } }Branch on code, never on message: messages are written for people and
may change. The docs link lands on the code's row below.
Retry? says what a retry needs. Never means the same request will fail again however long you wait: change the request, the token or the account first. Later means wait and back off.
Tokens and auth
| Code | Status | Meaning | Retry? |
|---|---|---|---|
missing_api_key | 401 | No Authorization: Bearer header | Never: send a token |
invalid_api_key | 401 | The token is unknown, revoked or mistyped | Never: use a live token |
token_policy_missing | 401 | An old key with no token policy | Never: create a new token |
token_not_yet_valid | 401 | Before the token's start time | Later, after the start time |
token_expired | 401 | After the token's expiry | Never: roll or replace the token |
key_expired | 401 | The key itself has expired | Never: replace the token |
key_disabled | 401 | The key was turned off | Never: use another token |
rate_limited | 401 | More than 300 requests in a minute on this token | Later, after the minute |
key_without_org | 400 | The token belongs to no workspace | Never: create the token inside a workspace |
secret_key_required | 403 | The endpoint needs a secret bw_sk_ token | Never: use a secret token, server-side |
publishable_key_write_denied | 403 | A publishable bw_pk_ token tried to change something | Never: use a secret token |
token_permission_denied | 403 | The token was not granted this action | Never: grant it, or use a token that has it |
key_role_denied | 403 | The token was granted it, but its owner's role no longer allows it | Never: an owner or admin changes the role |
token_resource_denied | 403 | The project, backend or zone is outside the token's resources, or a limited token tried to create one | Never: widen the token's resources |
token_ip_denied | 403 | The request came from outside the token's client IP filter | Never from that address |
token_owner_removed | 403 | The member who owns the token left the workspace | Never: create a workspace token |
disabled | 403 | Terminal commands are turned off on this platform | Never |
See API tokens.
Money
| Code | Status | Meaning | Retry? |
|---|---|---|---|
insufficient_balance | 402 | The wallet's available balance cannot cover this. Nothing was charged. Domain purchases add priceMinor and availableMinor | After a top-up |
workspace_suspended | 402 | Hosting is stopped until the wallet is topped up | After a top-up |
plan_limit | 403 | The workspace's plan does not allow another project, backend, custom domain, member or live preview. The body adds limit, max, used, plan and upgradeTo. Nothing was created | After choosing a plan that allows more, or removing one |
idempotency_key_reuse_mismatch | 409 | This idempotency key was already used with different content | Never: use a new key for a new request |
See Billing.
Requests
| Code | Status | Meaning | Retry? |
|---|---|---|---|
invalid, invalid_request | 400 | The body is not valid JSON, a field is missing or wrong (message names it), or a change changes nothing | Never: fix the body |
invalid_name | 400 | A name breaks the naming rules (backends: 2-31 lowercase letters, digits and hyphens) | Never |
invalid_type | 400 | A project type other than frontend or backend | Never |
not_found | 404 | No such resource, or the token cannot see it | Never |
Deploy, services and jobs
| Code | Status | Meaning | Retry? |
|---|---|---|---|
invalid_port | 400 | A port outside 1-65535, or a port on a worker or cron job (they listen on none) | Never |
invalid_cron_schedule | 400 | Not a five-field cron schedule | Never |
invalid_timeout | 400 | A time limit outside what the endpoint allows, or a run time limit on a service that is not a cron job | Never |
command_required | 400 | No command to run | Never |
invalid_command | 400 | The command is not text, is longer than 4,096 characters, or contains a NUL character | Never |
no_container | 409 | The project has no running container for a Terminal command | After a deploy |
not_deployed | 409 | A job runs on the service's live release, and it has none yet | After a deploy |
not_cancellable | 409 | A pre-deploy command cannot be cancelled; it fails its deploy at its time limit | Never |
already_finished | 409 | The job you tried to cancel already finished | Never |
too_many_jobs | 429 | Three jobs are already running on this service | Later, when one ends |
confirmation_required | 400 | Deleting a backend needs confirm set to its name | Never: send the confirmation |
hosting_unavailable | 503 | The hosting engine could not be reached | Later |
secrets_unavailable | 503 | Encrypted settings could not be read just now | Later |
See Services and Jobs and cron.
SMS
| Code | Status | Meaning | Retry? |
|---|---|---|---|
invalid_recipient | 400 | to is not a phone number BWEZE can send to | Never |
empty_body | 400 | The message would be empty | Never |
message_too_long | 400 | More than 10 segments | Never: shorten it |
recipient_opted_out | 409 | The recipient texted STOP | Never, until they opt back in |
messaging_rejected | 4xx | The SMS gateway refused the message; message says why | Never as is |
messaging_unavailable | 503 | The SMS gateway could not be reached | Later, with the same idempotency key |
See Messaging.
Domains and DNS
| Code | Status | Meaning | Retry? |
|---|---|---|---|
invalid_domain | 400 | Not a domain name BWEZE accepts | Never |
domain_not_sold | 400 | BWEZE does not sell this suffix, or it is a subdomain | Never |
registrant_required | 400 | No owner details sent and none saved for the workspace | Never: send registrant |
invalid_registrant | 400 | An owner field is missing or malformed; message names it | Never |
domain_taken | 409 | The domain is already registered | Never |
domain_unavailable | 409 | The domain is already being bought through BWEZE | Never |
domain_reserved | 409 | That *.bweze.app name is in use or reserved | Never: pick another name |
invalid_record, invalid_dns_input | 400 | A DNS record's name, type, TTL or value is not valid | Never |
zone_exists | 409 | That zone already exists | Never |
dns_unavailable | 503 | The nameservers could not be reached | Later |
Anything else
| Code | Status | Meaning | Retry? |
|---|---|---|---|
internal_error | 500 | Something broke on BWEZE's side | Later; if it keeps happening, write to [email protected] with the time and the request |