Errors and Status Codes

Tsara uses the HTTP status code together with the JSON envelope.

Common status code patterns

Request succeeded.

Invalid request payload, missing required input, or unsupported combination.

Unauthorized. Usually means the wrong key type or an invalid token was supplied.

Requested resource was not found.

Conflict, duplicate, or insufficient-balance condition depending on the endpoint.

Structured validation failure.

Internal application error.

Upstream provider failure or provider rejection when Tsara cannot return a cleaner downstream code.

Temporary service unavailability, commonly when a provider quote or provisioning dependency is unavailable.

always read both the HTTP status code and message
if errors is present, show or log field-level validation details
treat 502 and 503 as retry-aware conditions, not as permanent client-side validation errors
when using idempotent flows, retry with the same idempotency key where supported