Error Handling

The Turris Public API uses conventional HTTP response codes and returns detailed error information to help you handle issues gracefully.

HTTP Status Codes

Status Code	Meaning
`200`	Success - Request completed successfully
`201`	Created - Resource was created successfully
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Missing or invalid authentication
`403`	Forbidden - Valid auth but insufficient permissions
`404`	Not Found - Resource doesn’t exist
`422`	Unprocessable Entity - Validation failed
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong on our end

Error Response Format

All error responses follow a consistent format:

{
  "statusCode": 400,
  "requestId": "dev-63c50377-1cfa-4d51-bce7-d187507853db",
  "errorType": "validation_error",
  "errorMessage": ["Field 'npn' is required"],
  "timestamp": "2025-01-30T09:58:12.488Z"
}

Response Fields

Field	Type	Description
`statusCode`	number	HTTP status code
`requestId`	string	Unique identifier for this request (useful for support)
`errorType`	string	Machine-readable classification. Branch on this, not on the message
`errorMessage`	string[]	Array of human-readable error messages. Always an array, even for one error
`timestamp`	string	ISO 8601 timestamp of when the error occurred
`details`	object	Additional context, when the error has any

errorMessage is prose and may be reworded without notice. errorType is a published enum — every endpoint’s error schema in the API reference lists the complete set of values.One exception to plan for: authentication failures returned by our identity provider are forwarded verbatim, so a 401 can carry a code outside the published list. Treat an unrecognised value as a generic failure of its HTTP status rather than as a parsing error.

Error Types

The most common values. The full enum is on every endpoint’s error schema in the API reference.

`unauthorized`

Authentication failed or was not provided.

{
  "statusCode": 401,
  "errorType": "unauthorized",
  "errorMessage": ["Authentication token not provided"]
}

Common causes:

Missing Authorization header
Expired JWT token
Invalid token format

`forbidden`

Authentication succeeded but the request is not allowed.

{
  "statusCode": 403,
  "errorType": "forbidden",
  "errorMessage": ["IP address \"192.168.1.1\" not in allowed list for token \"***-a5ed\""]
}

Common causes:

IP not in allowlist (for Restricted Access Tokens)
Insufficient permissions for the requested resource

forbidden is not the only 403. Calling the other persona’s surface returns invalid_organization_category, a missing entitlement returns product_feature_subscription_required, and a carrier at its associated-agency ceiling returns invite_limit_reached. Each has its own section below, because the fix for each is different. Branch on errorType.

`invalid_organization_category`

A 403 carrying this errorType means the credential is valid and the surface is wrong. A credential belongs to exactly one persona and none reaches both: a carrier credential reaches /v1/* and /v2/upstream/*, an agency credential reaches /v2/downstream/*.

{
  "statusCode": 403,
  "errorType": "invalid_organization_category",
  "errorMessage": ["This endpoint is scoped to upstreamEntity callers; this credential belongs to a downstreamEntity"]
}

Common causes:

An agency credential on a persona-scoped /v1/* route, or on /v2/upstream/* (the four /auth/* and /heartbeat routes carry no persona and serve either surface)
A carrier credential on /v2/downstream/*
One base URL reused for both surfaces

Nothing about the credential needs changing, so re-minting it will not help. To confirm which surface it is for, send the same token to GET /v2/auth/test-oauth: the response carries orgCategory, upstreamEntity or downstreamEntity (the enum also holds two enterprise values for surfaces that are not routable yet, so match rather than negate). Which API is mine? has the routing rules and the rest of the 403 breakdown.

`product_feature_subscription_required`

A 403 carrying this errorType means your credentials are fine and the entitlement is not. Entitlement is re-checked on every request, not only when the credential is created, so this can start appearing for an integration that worked yesterday. Three distinct causes, and the errorMessage names which one applies:

What the message says	What it means	What to do
No active Turris subscription	The organization is no longer a customer, so no endpoint is available	Contact support@turrisfi.com
The Public API feature is not enabled	The organization is a customer but the API itself is switched off	Contact support to enable Public API
This endpoint needs the <feature> feature	One surface needs a feature the rest of your integration does not. Everything else keeps working	Contact support to enable that feature

The third case is the one worth reading carefully: it is a single endpoint being unavailable, not your integration being broken. GET /v2/upstream/webhooks needs the Webhook Settings feature, for example, while the rest of the carrier API does not. This applies to carriers and agencies alike, on every version. Each area of the API needs the same product feature as the matching screen in the Turris application, so the mapping is the one you already know from the UI: if you can see a section, its endpoints are available to your credential. Getting Started and Getting Started for Agencies list it per endpoint group.

Carrier /v1/* endpoints are included. Entitlement was previously not checked there, so an organization whose subscription or Public API feature is switched off may start receiving 403 on v1 calls that used to succeed. The fix is the same as for any other cause above: the flags, not your code.

Entitlement is cached briefly, so a feature that has just been switched on can take up to a minute to take effect. Requesting a new token does not shorten that: the cache is keyed on your organization, not on the token.

`invite_limit_reached`

A 403 carrying this errorType is a plan limit, not a permission problem. It is raised on the carrier association-create endpoints, POST /v2/upstream/downstream-entity-associations/add and POST /v2/upstream/downstream-entity-associations/invite (POST /v1/downstream-entity-associations/add and /invite on v1), when the organization already holds as many live associated agencies as its plan allows.

{
  "statusCode": 403,
  "errorType": "invite_limit_reached",
  "errorMessage": ["You have reached the limit of downstream entities you can associate with your account"]
}

Retrying does not clear it. Remove an association you no longer need, or contact support@turrisfi.com to raise the ceiling. Nothing on the agency surface returns this code.

`validation_error`

Request validation failed.

{
  "statusCode": 400,
  "errorType": "validation_error",
  "errorMessage": [
    "npn must be a string",
    "stateCode must be a valid US state code"
  ]
}

Common causes:

Missing required fields
Invalid field formats
Mutually exclusive parameters provided together

`not_found`

The requested resource doesn’t exist.

{
  "statusCode": 404,
  "errorType": "not_found",
  "errorMessage": ["Agent with ID '507f1f77bcf86cd799439011' not found"]
}

A 404 also covers “exists, but is not yours.” On the agency surface, an id belonging to another organization returns 404 rather than 403 — a 403 would confirm the record exists, which is the same disclosure in a politer envelope. So a 404 on an id you believe is yours is worth checking against List Licensed Entities: the usual cause is a credential minted lower in your organization tree than you expected.

`internal_server_error`

Something went wrong on our servers.

{
  "statusCode": 500,
  "errorType": "internal_server_error",
  "errorMessage": ["An unexpected error occurred"]
}

If you receive a 500 error, please contact support with the requestId for investigation.

Handling Errors

Example: JavaScript/TypeScript

const BASE_URL = 'https://public.api.live.turrisfi.com';

async function callTurris(path: string, attempt = 0) {
  try {
    const response = await fetch(
      `${BASE_URL}${path}`,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`
        }
      }
    );

    if (!response.ok) {
      const error = await response.json();

      switch (error.statusCode) {
        case 401:
          // Token expired - refresh once, then give up
          if (attempt >= 1) break;
          await refreshToken();
          return callTurris(path, attempt + 1);
        case 429: {
          // Rate limited - honour Retry-After, cap the attempts
          if (attempt >= 3) break;
          const retryAfter = Number(response.headers.get('Retry-After')) || 60;
          await sleep(retryAfter * 1000);
          return callTurris(path, attempt + 1);
        }
        case 400:
          // Bad request - log and don't retry
          console.error('Validation error:', error.errorMessage);
          throw new Error(error.errorMessage.join(', '));
      }

      // Retries exhausted, or a status with no retry rule
      throw new Error(`API error: ${error.errorMessage.join(', ')}`);
    }

    return response.json();
  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}

// Shared by both surfaces: any credential can call these
await callTurris('/v2/heartbeat');
await callTurris('/v2/auth/test-oauth');

// The same function serves whichever surface your credential is for
await callTurris('/v2/upstream/agents');      // carrier credential
await callTurris('/v2/downstream/producers'); // agency credential

Example: Python

import requests
import time

BASE_URL = 'https://public.api.live.turrisfi.com'

def call_turris(path: str, access_token: str, retry_count: int = 0):
    try:
        response = requests.get(
            f'{BASE_URL}{path}',
            headers={'Authorization': f'Bearer {access_token}'}
        )

        if response.status_code == 200:
            return response.json()

        error = response.json()

        if response.status_code == 401 and retry_count < 1:
            # Token expired - refresh and retry
            new_token = refresh_token()
            return call_turris(path, new_token, retry_count + 1)

        if response.status_code == 429 and retry_count < 3:
            # Rate limited - wait and retry
            time.sleep(60)
            return call_turris(path, access_token, retry_count + 1)

        raise Exception(f"API error: {', '.join(error['errorMessage'])}")

    except requests.RequestException as e:
        print(f"Request failed: {e}")
        raise

# Shared by both surfaces: any credential can call these
call_turris('/v2/heartbeat', access_token)
call_turris('/v2/auth/test-oauth', access_token)

# The same function serves whichever surface your credential is for
call_turris('/v2/upstream/agents', access_token)       # carrier credential
call_turris('/v2/downstream/producers', access_token)  # agency credential

Best Practices

Always check the status code

Don’t assume requests succeed. Check the HTTP status code and handle errors appropriately.

Log the requestId

The requestId is essential for debugging. Log it when errors occur so you can reference it when contacting support.

Implement retry logic

For transient errors (429, 500, 503), implement exponential backoff retry logic.

Handle token expiration gracefully

OAuth tokens expire after 60 minutes. Implement proactive token refresh or handle 401 errors by refreshing and retrying.

Start Here

API Conventions

Tools & Integrations

Support

Error Handling

Error Handling

HTTP Status Codes

Error Response Format

Response Fields

Error Types

`unauthorized`

`forbidden`

`invalid_organization_category`

`product_feature_subscription_required`

`invite_limit_reached`

`validation_error`

`not_found`

`internal_server_error`

Handling Errors

Example: JavaScript/TypeScript

Example: Python

Best Practices

​Error Handling

​HTTP Status Codes

​Error Response Format

​Response Fields

​Error Types

​unauthorized

​forbidden

​invalid_organization_category

​product_feature_subscription_required

​invite_limit_reached

​validation_error

​not_found

​internal_server_error

​Handling Errors

​Example: JavaScript/TypeScript

​Example: Python

​Best Practices

Error Handling

HTTP Status Codes

Error Response Format

Response Fields

Error Types

`unauthorized`

`forbidden`

`invalid_organization_category`

`product_feature_subscription_required`

`invite_limit_reached`

`validation_error`

`not_found`

`internal_server_error`

Handling Errors

Example: JavaScript/TypeScript

Example: Python

Best Practices