Error Handling

The Trudenty Consumer Trust Index (CTI) API uses standard HTTP status codes and structured JSON error responses to indicate the outcome of API requests.

This guide explains how the API communicates errors and provides recommendations for handling them in your application.

Error Response Format

Most error responses include the following fields.

Field	Description
`status`	Indicates the request outcome.
`request_id`	Unique request identifier for troubleshooting.
`message`	Human-readable description of the error.

Example:

{
  "status": "error",
  "request_id": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Authentication failed."
}

HTTP status codes

HTTP Status	When It Occurs
200	Successful request
400	Missing credentials, missing/invalid parameters, invalid date format, invalid date range
401	Invalid client ID or client secret
403	Partner account suspended or revoked
404	No trust index record found (latest CTI endpoint only)
413	Request body exceeds size limit
429	Rate limit exceeded
500	Internal server error

Authentication & Authorization errors

HTTP Status	Message	Description
400	Missing credentials. Provide x-client-id and x-client-secret headers.	One or both authentication headers are missing
401	Authentication failed. The x-client-id header value is invalid or not registered.	Client ID not found
401	Authentication failed. The x-client-secret header value is invalid.	Client secret does not match
401	Unauthorized	Generic unauthorized response
403	Your partner account is currently suspended.	Partner account is suspended
403	Your partner account has been revoked.	Partner account is revoked
403	Your partner account is not active.	Partner account is not active

Validation errors

HTTP Status	Message	Description
400	At least one consumer id is required	Query parameter `consumer_id` is missing or empty
400	from_date must be a valid date in YYYY-MM-DD format	Invalid `from_date` query parameter
400	to_date must be a valid date in YYYY-MM-DD format	Invalid `to_date` query parameter
400	from_date must be before or equal to to_date	Date range is invalid
400	Invalid JSON body received	Malformed JSON in request body
413	Request body too large: {size} bytes exceeded the limit	Request payload exceeds allowed size

Business & server errors

HTTP Status	`status` field	Message	Description
404	`no_network_record`	No Trust Index record found for the supplied consumer attributes.	No CTI data exists for the given `consumer_id`
429	-	Too many requests. Please try again after 1 minute.	Rate limit exceeded
500	`error`	Internal server error	Unexpected server-side failure

Rate limiting

Rate-limited responses are returned directly by the rate limiter and do not include a status or message field:

{
  "error": "Too many requests. Please try again after 1 minute."
}

Rate limit: 500 requests per minute per client IP address. Monitor the RateLimit-Remaining response header.

Need Assistance?
If you have questions about onboarding, authentication, or API integration, visit the Contact Support page to explore available support channels and contact our team.