The Trakkr API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error with our servers.

​
Error Response Format

All error responses follow this format:

{
  "error": "Error title",
  "errors": ["Detailed error message"]
}

​
HTTP Status Codes

Status CodeDescription
200Success - The request was successful
400Bad Request - The request was invalid
401Unauthorized - Missing or invalid API key
403Forbidden - Valid API key but insufficient permissions
500Internal Server Error - Something went wrong on our end

​
Common Error Responses

​
400 Bad Request

​
Missing Required Parameter

{
  "error": "Missing required parameter: brand",
  "errors": ["brand parameter is required"]
}

​
Invalid Breakdown Format

{
  "error": "Invalid breakdown parameter format",
  "errors": ["breakdown must be a valid JSON array"]
}

​
Invalid Breakdown Values

{
  "error": "Invalid breakdown values",
  "errors": ["Invalid breakdown values: ['invalid']. Valid values are: ['model', 'prompt']"]
}

​
Invalid Date Format

{
  "error": "Invalid start_date format",
  "errors": ["start_date must be in YYYY-MM-DD format"]
}

​
Date Range Too Large

{
  "error": "Date range too large",
  "errors": ["The total date range cannot exceed 90 days"]
}

​
401 Unauthorized

​
Missing API Key

{
  "error": "Missing API key",
  "errors": ["API key must be provided in the Authorization header as 'Bearer <api_key>'"]
}

​
403 Forbidden

​
Invalid API Key

{
  "error": "Invalid API key",
  "errors": ["No accounts found for this API key"]
}

​
Brand Access Denied

{
  "error": "Brand access denied",
  "errors": ["You do not have access to this brand"]
}

​
500 Internal Server Error

​
Authentication Error

{
  "error": "Authentication error",
  "errors": ["Could not validate API key against database"]
}

​
Date Range Validation Error

{
  "error": "Date range validation error",
  "errors": ["Could not validate date range: invalid date format"]
}

​
General Server Error

{
  "error": "Internal server error",
  "errors": ["An unexpected error occurred: [error details]"]
}

​
Handling Errors

​
JavaScript Example

try {
  const response = await fetch('https://api.trakkr.ai/get-scores', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      brand: '0000000000000x000000000000000000',
      breakdown: ['model']
    })
  });

  if (!response.ok) {
    const errorData = await response.json();
    console.error(`Error ${response.status}:`, errorData.error);
    console.error('Details:', errorData.errors);
    return;
  }

  const data = await response.json();
  console.log('Success:', data);
} catch (error) {
  console.error('Network error:', error);
}

​
Python Example

import requests

try:
    response = requests.post(
        'https://api.trakkr.ai/get-scores',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'brand': '0000000000000x000000000000000000',
            'breakdown': ['model']
        }
    )
    
    if response.status_code != 200:
        error_data = response.json()
        print(f"Error {response.status_code}: {error_data.get('error')}")
        print(f"Details: {error_data.get('errors')}")
    else:
        data = response.json()
        print('Success:', data)
        
except requests.exceptions.RequestException as e:
    print(f"Network error: {e}")

​
Error Handling Best Practices

  1. Check status codes: Always check the HTTP status code before processing the response
  2. Parse error messages: Extract both the error title and detailed messages
  3. Handle network errors: Catch and handle network-level exceptions
  4. Log errors: Log error details for debugging purposes
  5. Retry logic: Consider implementing retry logic for 5xx errors
  6. User feedback: Provide meaningful error messages to end users

​
Rate Limiting

While the API doesn’t have strict rate limits, we recommend:

  • Making reasonable numbers of requests
  • Implementing exponential backoff for retries
  • Caching responses when appropriate
  • Avoiding rapid-fire requests

Need help debugging? If you’re getting unexpected errors, check our authentication guide or contact support with the full error response.