Error handling

This guide covers error handling for the k-ID API, including common error codes, error response formats, and best practices for handling errors.

Error response format

All API errors follow a consistent response format. Error responses include an error field and an errorMessage field:

{
  "error": "ERROR_CODE",
  "errorMessage": "Human-readable error message"
}

HTTP status codes

The k-ID API uses standard HTTP status codes to indicate the result of API requests:

Status Code	Description	When It Occurs
200	OK	Request successful
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Common error codes

Authentication errors

UNAUTHORIZED

Status: 401
Description: Invalid or missing API key

{
  "error": "UNAUTHORIZED",
  "errorMessage": "Unauthorized"
}

Common causes:

• Missing Authorization header
• Invalid API key format
• Expired API key

Resolution:

• Verify API key is correct
• Check if key is active and not expired
• Ensure key is properly formatted in Authorization header

Request validation errors

INVALID_INPUT

Status: 400
Description: Request validation failed

{
  "error": "INVALID_INPUT",
  "errorMessage": "The age verification could not be found."
}

Resolution:

• Review validation error details
• Correct the invalid field values
• Refer to API documentation for valid values

Resource errors

Rate limiting errors

Status: 429
Description: Rate limit exceeded No Response Body

Resolution:

• Implement exponential backoff
• Reduce request frequency
• Cache responses when appropriate

Server errors

Status: 500
Description: Internal server error

{
  "error": "INTERNAL_ERROR",
  "errorMessage": "Internal server error"
}

Resolution:

• Retry the request after a delay
• Contact support if error persists
• Check service status page

Next steps

• API endpoints - Learn about available endpoints
• Authentication - Learn about API authentication