Errors & retries

Check the HTTP status before reading a successful result. Most API errors are JSON with an error string:

{ "error": "not authenticated" }

Error messages are intended to help a human diagnose the request. Branch your client logic on the status and operation context rather than matching an exact English error string. Proxies, network failures, and some specialized endpoints may return a different body.

Common statuses

Status	Meaning	Next step
200	Request completed	Read the response for the operation
201	Resource created	Store the returned identifier and inspect its state
202	Work accepted or queued	Follow the deployment or job until it completes
400	Invalid input or unsupported configuration	Check parameter names, types, and allowed values
401	Authentication missing or invalid	Check the Bearer header and whether the key was revoked
402	Billing blocks the action, where enforced	Resolve the account billing requirement in the dashboard
403	Access or key scope does not permit the action	Check permissions, project, and environment restrictions
404	Resource missing or not visible to you	Check the ID and scope; inaccessible resources may be hidden
409	Current resource state conflicts with the request	Inspect the service or active deployment before trying again
413	Payload exceeds the accepted limit	Reduce the archive or use the supported upload flow
429	Too many requests	Respect Retry-After when present and slow down
5xx	Server or upstream failure	Preserve context, back off, and inspect state before repeating a write

Not every operation uses every status. The operation pages describe successful responses and endpoint-specific errors. Authentication and authorization middleware can return additional errors before the handler runs.

Retry reads conservatively

For a transient read failure, use bounded exponential backoff with jitter. Honor a Retry-After header when it is returned. Do not retry authentication or validation failures unchanged.

There is no single published numeric rate limit for all authenticated operations. Limits can depend on the endpoint and platform configuration. Avoid tight polling loops; request incremental logs and reuse results where possible.

Inspect before repeating a write

The documented API does not promise an Idempotency-Key contract. A timeout after creation or deployment may mean the server accepted the request but the response did not reach you.

Before retrying:

1. Read the project or service and look for the resource or deployment.
2. If the first operation succeeded, continue using its identifier.
3. If its outcome remains unclear, inspect logs or contact support rather than repeatedly creating resources.

Creation requests can start billed resources. Restore, credential rotation, and SQL requests can affect data or running clients; retrying them requires particular care.

Treat a queued operation as a workflow

Deployment acceptance is the beginning of the workflow. Read deployment history, inspect build logs, then check the running service. A 202 response alone is not evidence that the application is healthy.

For help, include the operation, timestamp, HTTP status, and relevant resource ID. Remove API keys, database credentials, and secret environment values before sharing a request or log.