Error Handling

Learn about API error responses, error codes, and best practices for handling errors in your integration.

Error Response Format

The Trakkr API uses standard HTTP status codes and returns error details in a consistent JSON format. All errors include a type,code, and human-readable message.

type

The class of error (e.g., authentication_error)

code

A machine-readable error code for programmatic handling

message

A human-readable description of what went wrong

param

The specific parameter that caused the error (when applicable)

doc_url

Link to documentation for this specific error

HTTP Status Codes

The API uses conventional HTTP response codes to indicate success or failure:

2xx

Success - Request was successful

4xx

Client error - Problem with your request

5xx

Server error - Something went wrong on our end

Code	Description
`200`	OK - Request succeeded
`201`	Created - Resource successfully created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - No permission to access resource
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong
`503`	Service Unavailable - Temporary outage

Error Types Reference

Detailed reference for all error types and their associated codes:

`authentication_error`

HTTP 401

Problems authenticating your request

`invalid_api_key`	The API key is invalid or malformed
`api_key_revoked`	The API key has been revoked
`api_key_expired`	The API key has expired
`missing_authorization`	No Authorization header provided

`invalid_request_error`

HTTP 400

Your request has invalid parameters

`invalid_param`	A request parameter is invalid
`missing_param`	A required parameter is missing
`invalid_json`	Request body is not valid JSON
`not_found`	The requested resource does not exist (404)

`rate_limit_error`

HTTP 429

Too many requests in a given time period

`rate_limit_exceeded`	Request rate limit exceeded
`daily_limit_exceeded`	Daily request quota exceeded

`api_error`

HTTP 500

An error occurred on our servers

`internal_error`	Internal server error
`service_unavailable`	Service temporarily unavailable
`timeout`	Request timed out

Best Practices

Handle all error types

Implement handlers for authentication errors, validation errors, rate limits, and server errors. Each requires different handling logic.

Log errors with context

Log the full error response including the request ID (from X-Request-Id header) for debugging and support requests.

Show user-friendly messages

Translate API error codes into helpful messages for your users. Don't expose technical error details directly.

Retry transient errors

Implement retry logic with exponential backoff for 5xx errors and 429 rate limits. Don't retry 4xx client errors.

Always check the HTTP status code first, then parse the error response body for detailed error information including the error type, code, and message.

Code Example

Error Handling

1# Errors are returned with appropriate HTTP status codes
2curl -i -H 'Authorization: Bearer $TRAKKR_API_KEY' \
3  'https://api.trakkr.ai/get-scores?brand_id=invalid_id'
4
5# HTTP/2 404
6# Content-Type: application/json
7# {
8#   "error": {
9#     "type": "invalid_request_error",
10#     "code": "not_found",
11#     "message": "Brand not found",
12#     "param": "brand_id"
13#   }
14# }

400 Bad Request

1{
2  "error": {
3    "type": "invalid_request_error",
4    "code": "invalid_param",
5    "message": "The 'name' field is required and cannot be empty.",
6    "param": "name",
7    "doc_url": "https://trakkr.ai/docs/errors#invalid_param"
8  }
9}

Error Handling

1# Errors are returned with appropriate HTTP status codes
2curl -i -H 'Authorization: Bearer $TRAKKR_API_KEY' \
3  'https://api.trakkr.ai/get-scores?brand_id=invalid_id'
4
5# HTTP/2 404
6# Content-Type: application/json
7# {
8#   "error": {
9#     "type": "invalid_request_error",
10#     "code": "not_found",
11#     "message": "Brand not found",
12#     "param": "brand_id"
13#   }
14# }

400 Bad Request

1{
2  "error": {
3    "type": "invalid_request_error",
4    "code": "invalid_param",
5    "message": "The 'name' field is required and cannot be empty.",
6    "param": "name",
7    "doc_url": "https://trakkr.ai/docs/errors#invalid_param"
8  }
9}