Errors and Status Codes

Tsara returns an HTTP status code and a JSON response envelope. Use both: the HTTP code determines your retry strategy, while message and optional errors explain what needs attention.

Common status codes

Code	Meaning	Recommended action
`200`	Request accepted or completed	Inspect `data.status` for asynchronous resources
`400`	Invalid input or unsupported combination	Correct the request before retrying
`401`	Missing, invalid, expired, or incorrect credential type	Check authentication and environment
`403`	Authenticated but the feature or action is not available	Check business access and feature configuration
`404`	Resource was not found for the authenticated business	Verify the identifier and environment
`409`	Conflict, duplicate request, invalid state, or insufficient available balance	Read `message`; reconcile before retrying
`422`	Structured validation failure	Display or log field-level `errors`
`500`	Unexpected application error	Retry cautiously and escalate if persistent
`502`	A downstream operation failed or was rejected	Reconcile status before attempting another money movement
`503`	A required service is temporarily unavailable	Retry with backoff using the same idempotency key where supported

Validation example

{
  "success": false,
  "status": "failed",
  "status_code": 422,
  "message": "Validation failed",
  "errors": {
    "amount": ["Amount is required."],
    "currency": ["Currency is not supported."]
  }
}

Retry safely

do not automatically retry 400, 401, 403, 404, or 422 responses without changing the cause
for timeouts, 500, 502, or 503, first query the resource by your reference when a status endpoint exists
reuse the same idempotency key on retry when the endpoint supports it
never generate a new business reference merely because the client timed out; the original operation may still complete
use bounded exponential backoff instead of tight polling loops

Preserve diagnostic context

Log the HTTP code, top-level message, your business reference, the Tsara identifier, and the resource status. Never log secret keys, webhook secrets, OTPs, or full sensitive identity values.