Error Handling

The Tiptree Platform API uses standard HTTP status codes and a consistent error response format to communicate errors. This guide explains how to handle errors when using the API.

Error Response Format

All API errors follow a consistent JSON format:

{
  "error": {
    "code": "error_code",
    "message": "A human-readable error message",
    "details": {
      // Additional error-specific information
    }
  }
}

• code: A machine-readable error code that can be used to programmatically handle specific error types
• message: A human-readable description of the error
• details: An optional object containing additional information about the error

HTTP Status Codes

The API uses the following HTTP status codes:

Status Code	Description
200 OK	The request was successful
201 Created	The resource was successfully created
400 Bad Request	The request was invalid or malformed
401 Unauthorized	Authentication is required or failed
403 Forbidden	The authenticated user doesn’t have permission
404 Not Found	The requested resource doesn’t exist
409 Conflict	The request conflicts with the current state
422 Unprocessable Entity	The request was well-formed but contains semantic errors
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	An unexpected error occurred on the server
503 Service Unavailable	The service is temporarily unavailable

Common Error Codes

Authentication Errors

Error Code	Description
invalid_api_key	The API key is invalid or has been revoked
expired_api_key	The API key has expired
missing_api_key	No API key was provided
invalid_oauth_token	The OAuth token is invalid or has been revoked
expired_oauth_token	The OAuth token has expired

Resource Errors

Error Code	Description
resource_not_found	The requested resource doesn’t exist
resource_already_exists	A resource with the same identifier already exists
resource_conflict	The request conflicts with the current state of the resource

Validation Errors

Error Code	Description
invalid_request	The request is malformed or missing required fields
invalid_parameter	One or more parameters have invalid values
missing_parameter	A required parameter is missing

Rate Limiting Errors

Error Code	Description
rate_limit_exceeded	You’ve exceeded the rate limit for this endpoint

Error Handling Examples

Example 1: Invalid API Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked"
  }
}

Example 2: Resource Not Found

{
  "error": {
    "code": "resource_not_found",
    "message": "The agent with ID 'agent_123' was not found"
  }
}

Example 3: Validation Error

{
  "error": {
    "code": "invalid_parameter",
    "message": "One or more parameters have invalid values",
    "details": {
      "errors": [
        {
          "field": "name",
          "message": "Name must be between 1 and 100 characters"
        },
        {
          "field": "model",
          "message": "Model must be one of: gpt-4, gpt-3.5-turbo"
        }
      ]
    }
  }
}

Example 4: Rate Limit Exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You've exceeded the rate limit for this endpoint",
    "details": {
      "rate_limit": {
        "limit": 100,
        "remaining": 0,
        "reset": 1609459200
      }
    }
  }
}

Best Practices for Error Handling

When integrating with the Tiptree Platform API, follow these best practices for error handling:

1. Check HTTP status codes: Always check the HTTP status code first to determine the general category of the error.

2. Parse error codes: Use the code field to programmatically handle specific error types.

3. Display error messages: The message field provides human-readable descriptions that can be displayed to users.

4. Implement retry logic: For transient errors (e.g., 429, 503), implement exponential backoff retry logic.

5. Log detailed errors: Log the complete error response for debugging purposes.

Client Library Error Handling

If you’re using one of our official client libraries, errors are automatically converted to exceptions:

Python

from tiptree.client import TiptreeClient
from tiptree.exceptions import TiptreeAPIError, ResourceNotFoundError, RateLimitExceededError

client = TiptreeClient(api_key="your-api-key")

try:
    agent = client.agents.get("non_existent_agent_id")
except ResourceNotFoundError as e:
    print(f"Agent not found: {e.message}")
except RateLimitExceededError as e:
    print(f"Rate limit exceeded. Try again after {e.reset_at}")
except TiptreeAPIError as e:
    print(f"API error: {e.code} - {e.message}")

TypeScript

import { TiptreeClient } from '@tiptree/client';
import { TiptreeAPIError, ResourceNotFoundError, RateLimitExceededError } from '@tiptree/client';

const client = new TiptreeClient({
  apiKey: 'your-api-key'
});

try {
  const agent = await client.agents.get('non_existent_agent_id');
} catch (error) {
  if (error instanceof ResourceNotFoundError) {
    console.log(`Agent not found: ${error.message}`);
  } else if (error instanceof RateLimitExceededError) {
    console.log(`Rate limit exceeded. Try again after ${error.resetAt}`);
  } else if (error instanceof TiptreeAPIError) {
    console.log(`API error: ${error.code} - ${error.message}`);
  } else {
    console.log(`Unexpected error: ${error}`);
  }
}

Troubleshooting Common Issues

Authentication Issues

If you’re experiencing authentication errors:

1. Verify that your API key is correct and hasn’t been revoked
2. Check that your API key has the necessary permissions
3. For OAuth tokens, ensure they haven’t expired

Rate Limiting

If you’re hitting rate limits:

1. Implement exponential backoff retry logic
2. Consider batching requests where possible
3. Cache responses to reduce the number of API calls

Validation Errors

For validation errors:

1. Check the details field for specific validation failures
2. Validate input data before sending it to the API
3. Refer to the API reference for parameter requirements