Overview

​

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:

err:system:category:specific

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:

{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "error": {
    "detail": "Authentication credentials were not provided",
    "status": 401,
    "title": "Unauthorized",
    "type": "https://unkey.com/docs/api-reference/errors-v2/unkey/authentication/missing"
  }
}

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