Error Reference

Complete guide to API error codes and how to handle them.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "message": "Human-readable error message",
  "errors": {
    "field_name": ["error description", "another error"],
    "another_field": ["error description"]
  }
}

Fields:

message - High-level summary
errors - Field-specific validation errors (optional)

HTTP Status Codes

401 Unauthorized

Authentication failed - missing or invalid API token.

Missing Token

{
  "message": "Authentication required",
  "errors": {
    "authorization": ["Invalid or missing token"]
  }
}

Invalid/Expired Token

{
  "message": "Invalid or expired token"
}

How to Fix:

Ensure you're including the Authorization header
Use format: Authorization: Bearer cya_your_token
Check that your token hasn't been revoked
Generate a new token if needed

403 Forbidden

Token is valid but lacks required permissions.

{
  "message": "Insufficient permissions",
  "errors": {
    "scope": ["Token missing required scope: content:submit"]
  }
}

How to Fix:

Ensure your token has the content:submit scope
Check token permissions in your dashboard
Generate a new token with correct scopes if needed

422 Unprocessable Entity

Request validation failed - invalid or missing required fields.

{
  "message": "Validation failed",
  "errors": {
    "input": ["can't be blank"],
    "output": ["can't be blank"],
    "confidence": ["must be between 0.0 and 1.0"]
  }
}

429 Too Many Requests

Rate limit exceeded - too many requests in a short time period.

{
  "message": "Rate limit exceeded. Please try again later."
}

Response Headers:

Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0

How to Handle:

Wait for Retry-After seconds before retrying
Implement exponential backoff in your retry logic
Monitor X-RateLimit-Remaining header
Contact us if you need higher rate limits

Current Limit: 100 requests per 5 minutes per API token

500 Internal Server Error

An unexpected error occurred on our server.

{
  "message": "Internal server error. Please try again later."
}

What to Do:

Retry the request after a short delay
If the error persists, contact support@checkyourai.com
Include the request timestamp and any error details

Implementing Retry Logic

For production applications, implement proper retry logic with exponential backoff:

Retry Strategy

Status Code	Should Retry?	Strategy
401, 403	No	Fix authentication/permissions, don't retry
422	No	Fix request validation errors, don't retry
429	Yes	Wait for Retry-After seconds
500, 502, 503, 504	Yes	Exponential backoff (1s, 2s, 4s, 8s)
Network errors	Yes	Exponential backoff, max 3-5 attempts

Troubleshooting

"Invalid or missing token" error

Verify the Authorization header is included
Check format: Bearer cya_xxx
Ensure no extra spaces or characters
Confirm token starts with cya_

Rate limit errors (429)

Implement request queuing and batching
Use the Retry-After header
Consider caching review results
Contact support for higher limits if needed

Webhook delivery failures

Verify your endpoint is publicly accessible
Check that you're returning 2xx status codes
Ensure your endpoint responds within 10 seconds
Check firewall and SSL certificate configuration

Next Steps

API Reference

Complete API documentation with all request/response details.

Webhooks

Set up and troubleshoot webhook integrations.