Skip to main content
All responses from the Turris API follow a consistent structure to facilitate integration and debugging.

​
Top-Level Structure

Each response, whether successful or erroneous, includes a requestId field which can be used for tracing and support purposes. Response payloads are returned directly at the top level and are not wrapped in a data object. 
{
  "requestId": "dev-d9ff9170-cc06-4fa0-8177-8f1d34405a48",
  "timestamp": "2023-10-16T12:34:56Z",
  ...responseData
}

​
Date Format

All date and timestamp fields are returned in ISO 8601 format: 
2025-03-17T10:15:45.000Z
This is consistent with standard MongoDB date representations.

​
Identifier Format

All unique identifiers (e.g., agencyId, agentId, policyId) are returned as MongoDB ObjectId strings: 
5f1e88b5b8f1c8001cfb7d9a

​
Request Headers

​
Required Headers

HeaderValueDescription
Content-Typeapplication/jsonRequired for POST/PUT/PATCH requests
AuthorizationBearer <token>OAuth JWT token

​
Alternative Authentication

HeaderValueDescription
x-restricted-access-token<token>Restricted access token (alternative to OAuth)

​
Optional Headers

HeaderValueDescription
idempotency-keyUUID v4For idempotent operations
x-idempotency-keyUUID v4Alternative idempotency header

​
Success Responses

Successful responses return the data directly with standard metadata: 
{
  "requestId": "dev-d9ff9170-cc06-4fa0-8177-8f1d34405a48",
  "statusCode": 200,
  "timestamp": "2023-10-16T12:34:56Z",
  "data": {
    // Response payload
  }
}

​
Error Responses

Error responses follow a standardized schema. For detailed information about error handling, refer to the Error Handling guide. 
{
  "statusCode": 400,
  "requestId": "dev-d9ff9170-cc06-4fa0-8177-8f1d34405a48",
  "errorType": "invalid_input",
  "errorMessage": ["Field 'email' is required"],
  "timestamp": "2023-10-16T12:34:56Z"
}

​
HTTP Status Codes

CodeMeaning
200Success
201Created
400Bad Request - Invalid input
401Unauthorized - Invalid or expired token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Server Error - Internal error