Understand API errors

The platform returns a stable error code, a human-readable message, and a correlation ID for rejected requests. Use the code for program logic. Keep the correlation ID when reporting an issue; avoid sending credentials or full authorization headers.

Code	What to check
`invalid_request`	Check the JSON shape and required fields against the API reference.
`authentication_required`	Check that a test key is present, active, and sent as a bearer credential.
`authorization_denied`	Check that the key belongs to the correct project and has the needed scope.
`conflict`	Refresh the resource and check whether another operation changed it.
`not_found`	Check the resource ID and project context.
`capability_unavailable`	The requested environment or feature has not been released. Do not retry it as if it were a temporary outage.
`rate_limited`	Slow down and follow the response’s retry guidance.
`service_unavailable`	Retry a safe read after the service is healthy. Do not assume a value-moving operation can be replayed.

The exact HTTP status and response schema for each operation come from the versioned OpenAPI contract. A network failure can happen before an API error is returned, so log the request context without logging the secret.

A successful whoami response proves the credential was accepted by that API instance. It does not prove owner authorization or chain settlement.

Start here

Get started

Guides

Reference

Understand API errors