Errors & Response Format

Tsara APIs use standard HTTP response codes and structured JSON error messages to indicate success or failure.
Every response — whether successful or failed — follows a consistent format for easy parsing and debugging.

✅ Success Response Format

Successful responses always include:

success: Boolean value (true)
data: The requested resource or object
request_id: Unique identifier for tracking each API call

Example

{
  "success": true,
  "data": {
    "id": "wal_123",
    "type": "stablecoin",
    "network": "solana",
    "asset": "USDC",
    "balance": "250.00"
  },
  "request_id": "req_abc123"
}

❌ Error Response Format

When an error occurs, Tsara returns an HTTP status code in the 4xx or 5xx range.
The response body includes details that help identify and fix the issue.

Structure

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "The provided wallet ID is invalid.",
    "hint": "Ensure that the wallet ID exists and is active."
  },
  "request_id": "req_xyz123"
}

📘 Common HTTP Status Codes

Status	Meaning	Example
200	✅ Success	Request completed successfully.
201	✅ Created	Resource successfully created (e.g., wallet, customer).
400	❌ Bad Request	Invalid or missing parameters.
401	🔒 Unauthorized	Missing or invalid API key or token.
403	🚫 Forbidden	Action not allowed for your API key.
404	❓ Not Found	Resource doesn’t exist or has been deleted.
409	⚠️ Conflict	Duplicate request or non-idempotent action.
422	🧩 Unprocessable Entity	Validation failed for input fields.
429	🕒 Rate Limit Exceeded	Too many requests — wait before retrying.
500	💥 Internal Server Error	Unexpected error on Tsara’s servers.
503	🧱 Service Unavailable	Temporary outage or scheduled maintenance.

🧾 Example: Invalid Request

HTTP 400

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "The 'amount' field is required.",
    "hint": "Include 'amount' in your JSON body and retry."
  },
  "request_id": "req_abc789"
}

🔐 Example: Invalid API Key

HTTP 401

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided.",
    "hint": "Check that your Authorization header uses the correct Bearer token."
  },
  "request_id": "req_def456"
}

⚡ Example: Rate Limiting

If your application exceeds the allowed number of requests, Tsara returns a rate-limit error.

HTTP 429

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please wait before retrying.",
    "hint": "Retry after 30 seconds."
  },
  "request_id": "req_lim001"
}

🧠 Best Practices

Always log the request_id for support or debugging.
Handle 422 and 429 gracefully — prompt users to fix input or wait.
Avoid retrying 4xx errors except 429 (rate limits).
Implement exponential backoff for retries on 5xx responses.
Use sandbox mode to test error handling before going live.

🔗 Related Pages

Authentication — Learn how to use Bearer tokens with every request.
Webhooks — Securely validate webhook signatures.
Pagination — Handle list responses with multiple pages of data.