Errors and troubleshooting

Errors use the common JSON envelope documented in the API reference. Log the response request ID together with your own operation ID, without logging credentials or customer message bodies.

HTTP status	Typical action
`400`, `422`	Correct the input using the error details
`401`	Check key expiry, revocation, and bearer authentication
`403`	Check scopes, account eligibility, and connection access
`404`	Verify the opaque ID is visible to this key
`409`	Reread ownership or resolve an idempotency conflict
`429`	Wait according to `Retry-After`
`5xx` or lost response	Retry the same logical reply with the same idempotency key

Inspect the structured error code and retryability flag; status alone does not explain the failure. A conflict while an identical request is still in progress can be retried after the returned delay. Never solve a timeout by generating a fresh idempotency key.

For read failures, confirm that the inbox is explicitly granted to the key. A resource outside those grants deliberately appears missing.