BWEZE Docs

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

CodeStatusMeaningRetry?
missing_api_key401No Authorization: Bearer headerNever: send a token
invalid_api_key401The token is unknown, revoked or mistypedNever: use a live token
token_policy_missing401An old key with no token policyNever: create a new token
token_not_yet_valid401Before the token's start timeLater, after the start time
token_expired401After the token's expiryNever: roll or replace the token
key_expired401The key itself has expiredNever: replace the token
key_disabled401The key was turned offNever: use another token
rate_limited401More than 300 requests in a minute on this tokenLater, after the minute
key_without_org400The token belongs to no workspaceNever: create the token inside a workspace
secret_key_required403The endpoint needs a secret bw_sk_ tokenNever: use a secret token, server-side
publishable_key_write_denied403A publishable bw_pk_ token tried to change somethingNever: use a secret token
token_permission_denied403The token was not granted this actionNever: grant it, or use a token that has it
key_role_denied403The token was granted it, but its owner's role no longer allows itNever: an owner or admin changes the role
token_resource_denied403The project, backend or zone is outside the token's resources, or a limited token tried to create oneNever: widen the token's resources
token_ip_denied403The request came from outside the token's client IP filterNever from that address
token_owner_removed403The member who owns the token left the workspaceNever: create a workspace token
disabled403Terminal commands are turned off on this platformNever

See API tokens.

Money

CodeStatusMeaningRetry?
insufficient_balance402The wallet's available balance cannot cover this. Nothing was charged. Domain purchases add priceMinor and availableMinorAfter a top-up
workspace_suspended402Hosting is stopped until the wallet is topped upAfter a top-up
plan_limit403The 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 createdAfter choosing a plan that allows more, or removing one
idempotency_key_reuse_mismatch409This idempotency key was already used with different contentNever: use a new key for a new request

See Billing.

Requests

CodeStatusMeaningRetry?
invalid, invalid_request400The body is not valid JSON, a field is missing or wrong (message names it), or a change changes nothingNever: fix the body
invalid_name400A name breaks the naming rules (backends: 2-31 lowercase letters, digits and hyphens)Never
invalid_type400A project type other than frontend or backendNever
not_found404No such resource, or the token cannot see itNever

Deploy, services and jobs

CodeStatusMeaningRetry?
invalid_port400A port outside 1-65535, or a port on a worker or cron job (they listen on none)Never
invalid_cron_schedule400Not a five-field cron scheduleNever
invalid_timeout400A time limit outside what the endpoint allows, or a run time limit on a service that is not a cron jobNever
command_required400No command to runNever
invalid_command400The command is not text, is longer than 4,096 characters, or contains a NUL characterNever
no_container409The project has no running container for a Terminal commandAfter a deploy
not_deployed409A job runs on the service's live release, and it has none yetAfter a deploy
not_cancellable409A pre-deploy command cannot be cancelled; it fails its deploy at its time limitNever
already_finished409The job you tried to cancel already finishedNever
too_many_jobs429Three jobs are already running on this serviceLater, when one ends
confirmation_required400Deleting a backend needs confirm set to its nameNever: send the confirmation
hosting_unavailable503The hosting engine could not be reachedLater
secrets_unavailable503Encrypted settings could not be read just nowLater

See Services and Jobs and cron.

SMS

CodeStatusMeaningRetry?
invalid_recipient400to is not a phone number BWEZE can send toNever
empty_body400The message would be emptyNever
message_too_long400More than 10 segmentsNever: shorten it
recipient_opted_out409The recipient texted STOPNever, until they opt back in
messaging_rejected4xxThe SMS gateway refused the message; message says whyNever as is
messaging_unavailable503The SMS gateway could not be reachedLater, with the same idempotency key

See Messaging.

Domains and DNS

CodeStatusMeaningRetry?
invalid_domain400Not a domain name BWEZE acceptsNever
domain_not_sold400BWEZE does not sell this suffix, or it is a subdomainNever
registrant_required400No owner details sent and none saved for the workspaceNever: send registrant
invalid_registrant400An owner field is missing or malformed; message names itNever
domain_taken409The domain is already registeredNever
domain_unavailable409The domain is already being bought through BWEZENever
domain_reserved409That *.bweze.app name is in use or reservedNever: pick another name
invalid_record, invalid_dns_input400A DNS record's name, type, TTL or value is not validNever
zone_exists409That zone already existsNever
dns_unavailable503The nameservers could not be reachedLater

See Domains and DNS.

Anything else

CodeStatusMeaningRetry?
internal_error500Something broke on BWEZE's sideLater; if it keeps happening, write to [email protected] with the time and the request

On this page