Introduction#
Unkey's error system uses a structured approach to organize and identify errors across the platform. This system makes it easier to understand, debug, and handle errors consistently.
Error Code Format#
All Unkey error codes follow a consistent URN-like format:
For example: err:unkey:authentication:missing
This format breaks down as follows:
- err: Standard prefix for all error codes
- system: The service area or responsibility domain (e.g., unkey, user)
- category: The error type or classification (e.g., authentication, data)
- specific: The exact error condition (e.g., missing, malformed)
Systems#
The "system" component identifies where the error originated:
- unkey: Errors originating from Unkey's internal systems
- github: Errors related to GitHub integration
- aws: Errors related to AWS integration
Categories#
The "category" component provides a second level of classification, for example:
- authentication: Errors related to the authentication process
- authorization: Errors related to permissions and access control
- application: Errors related to application operations and system integrity
- data: Errors related to data operations and resources
- limits: Rate limiting or quota-related errors
Error Response Format#
When an error occurs, the API returns a consistent JSON response format:
Key fields:
- requestId: Unique identifier for the request (important for support)
- detail: Human-readable explanation of the error
- status: HTTP status code
- title: Short summary of the error type
- type: URL to detailed documentation about this error
Documentation Integration#
All error codes have a corresponding documentation page accessible via the type URL in the error response. These pages provide detailed information about:
- What caused the error
- How to fix the issue
- Common mistakes that lead to this error
- Related errors you might encounter