Error Codes

The Tholos API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error response format

All error responses follow this structure:

{
  "detail": "A human-readable description of the error"
}

Validation errors

Validation errors (422) use a different format with field-level details:

{
  "errors": [
    {
      "field": "body -> amount",
      "message": "value is not a valid integer"
    },
    {
      "field": "body -> chain",
      "message": "Input should be 'ethereum', 'polygon', ..."
    }
  ]
}

HTTP status codes

Success codes

Code	Meaning	Usage
200 OK	Request succeeded	GET requests, most POST responses with a body
201 Created	Resource created	POST requests that create a new resource
204 No Content	Success with no body	PUT, PATCH, DELETE operations

Client error codes

Code	Meaning	Common causes
400 Bad Request	Invalid request	Missing required fields, invalid parameter values, business logic violations (e.g., insufficient balance)
401 Unauthorized	Authentication failed	Missing or invalid token, expired PAT, disabled PAT
403 Forbidden	Insufficient permissions	Your role does not allow this operation, or you are not a member of the target vault/organization
404 Not Found	Resource not found	The requested vault, transaction, organization, or other resource does not exist, or you do not have access to it
409 Conflict	Resource conflict	Attempting to create a duplicate resource, or a concurrent edit conflict
422 Unprocessable Entity	Validation failed	Request body does not match the expected schema — see the errors array for field-level details
429 Too Many Requests	Rate limit exceeded	You have exceeded the endpoint’s rate limit — back off and retry

Server error codes

Code	Meaning	Action
500 Internal Server Error	Unexpected server error	Retry with exponential backoff. If persistent, contact support.

Common error scenarios

Authentication errors

// Missing or invalid token
// Status: 401
{
  "detail": "Not authenticated"
}

// Expired PAT
// Status: 401
{
  "detail": "Token has expired"
}

Permission errors

// Insufficient vault role
// Status: 403
{
  "detail": "User does not have the required vault role"
}

// Not a member of the organization
// Status: 403
{
  "detail": "User is not a member of this organization"
}

Business logic errors

// Trying to approve your own transaction
// Status: 400
{
  "detail": "Cannot approve your own transaction"
}

// Policy violation
// Status: 400
{
  "detail": "Transaction exceeds daily spending limit"
}

// Vault not active
// Status: 400
{
  "detail": "Vault is not in an active state"
}

Best practices

1. Always check the status code — don’t assume success
2. Parse the detail field for human-readable error messages
3. Handle 422 errors by iterating over the errors array for field-level feedback
4. Implement retry logic with exponential backoff for 429 and 500 errors
5. Log error responses to help debug integration issues

Note

Error messages are intended for developers, not end users. Do not display raw API error messages to your users — map them to user-friendly messages in your application.