feat: errors v2

apps/agent/go.mod

@@ -46,7 +46,7 @@ require (
 	github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6 // indirect
 	github.com/AlecAivazis/survey/v2 v2.3.7 // indirect
 	github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 // indirect
-	github.com/ClickHouse/ch-go v0.65.0 // indirect
+	github.com/ClickHouse/ch-go v0.64.1 // indirect
 	github.com/Masterminds/semver/v3 v3.3.0 // indirect
 	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/Microsoft/hcsshim v0.12.6 // indirect

apps/agent/go.sum

@@ -64,8 +64,8 @@ github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 h1:L/gRVlceqvL25
 github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
 github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
 github.com/BurntSushi/xgb v0.0.0-20160522181843-27f122750802/go.mod h1:IVnqGOEym/WlBOVXweHU+Q+/VP0lqqI8lqeDx9IjBqo=
-github.com/ClickHouse/ch-go v0.65.0 h1:vZAXfTQliuNNefqkPDewX3kgRxN6Q4vUENnnY+ynTRY=
-github.com/ClickHouse/ch-go v0.65.0/go.mod h1:tCM0XEH5oWngoi9Iu/8+tjPBo04I/FxNIffpdjtwx3k=
+github.com/ClickHouse/ch-go v0.64.1 h1:FWpP+QU4KchgzpEekuv8YoI/fUc4H2r6Bwc5WwrzvcI=
+github.com/ClickHouse/ch-go v0.64.1/go.mod h1:RBUynvczWwVzhS6Up9lPKlH1mrk4UAmle6uzCiW4Pkc=
 github.com/ClickHouse/clickhouse-go/v2 v2.31.0 h1:9MNHRDYXjFTJizGEJM1DfYAqdra/ohprPoZ+LPiuHXQ=
 github.com/ClickHouse/clickhouse-go/v2 v2.31.0/go.mod h1:V1aZaG0ctMbd8KVi+D4loXi97duWYtHiQHMCgipKJcI=
 github.com/DataDog/datadog-go v3.2.0+incompatible/go.mod h1:LButxg5PwREeZtORoXG3tL4fMGNddJ+vMq1mwgfaqoQ=

apps/docs/api-reference/errors-v2/overview.mdx

@@ -0,0 +1,80 @@
+---
+title: "Overview"
+description: "Understanding Unkey's structured error system"
+---
+
+<Warning>These errors are only for the v2 API, which is not yet GA.</Warning>
+
+
+## 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:
+
+```json
+{
+  "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

apps/docs/api-reference/errors-v2/unkey/application/assertion_failed.mdx

@@ -0,0 +1,57 @@
+---
+title: "err:unkey:application:assertion_failed"
+description: "A runtime assertion or invariant check failed"
+---
+
+
+```json Example
+{
+  "meta": {
+    "requestId": "req_2c9a0jf23l4k567"
+  },
+  "error": {
+    "detail": "A system integrity check failed while processing your request",
+    "status": 500,
+    "title": "Internal Server Error",
+    "type": "https://unkey.com/docs/api-reference/errors-v2/unkey/application/assertion_failed"
+  }
+}
+```
+
+## What Happened?
+
+This error occurs when Unkey's internal system detects an inconsistency or violation of its expected invariants during the processing of your request. Unlike validation errors which occur when your input is invalid, assertion failures happen when the system's internal state doesn't match what was expected.
+
+Possible causes include:
+- Data corruption or inconsistency in Unkey's database
+- Bugs in Unkey's business logic
+- Race conditions or timing issues
+- System state that violates core assumptions
+- Incompatible changes between different parts of the system
+
+This type of error is generally not caused by anything you did wrong in your request, but rather indicates an internal issue with Unkey's system integrity.
+
+## How To Fix
+
+Since this is an internal system error, there's usually nothing you can directly do to fix it. However, you can try the following:
+
+1. **Retry the request**: Some assertion failures may be due to temporary conditions that resolve themselves
+2. **Contact Unkey support**: Report the error with the request ID to help Unkey address the underlying issue
+3. **Check for workarounds**: In some cases, using a different API endpoint or approach might avoid the issue
+
+When contacting support, be sure to include:
+- The full error response, including the request ID
+- The API endpoint you were calling
+- The request payload (with sensitive information redacted)
+- Any patterns you've noticed (e.g., if it happens consistently or intermittently)
+
+## Important Notes
+
+- Assertion failures indicate bugs or data integrity issues that Unkey needs to fix
+- Unlike many other errors, changing your request is unlikely to resolve the issue
+- These errors are typically logged and monitored by Unkey's engineering team
+- If you encounter this error consistently, there may be an underlying issue with your account data
+
+## Related Errors
+- [err:unkey:application:unexpected_error](./unexpected_error) - A more general internal error
+- [err:unkey:application:service_unavailable](./service_unavailable) - When a service is temporarily unavailable

apps/docs/api-reference/errors-v2/unkey/application/invalid_input.mdx

@@ -0,0 +1,88 @@
+---
+title: "err:unkey:application:invalid_input"
+description: "Client provided input that failed validation"
+---
+
+
+```json Example
+{
+  "meta": {
+    "requestId": "req_2c9a0jf23l4k567"
+  },
+  "error": {
+    "detail": "The request contains invalid input that failed validation",
+    "status": 400,
+    "title": "Bad Request",
+    "type": "https://unkey.com/docs/api-reference/errors-v2/unkey/application/invalid_input",
+    "errors": [
+      {
+        "location": "body.limit",
+        "message": "must be greater than or equal to 1",
+        "fix": "Provide a limit value of at least 1"
+      }
+    ]
+  }
+}
+```
+
+## What Happened?
+
+This error occurs when your request contains input data that doesn't meet Unkey's validation requirements. This could be due to missing required fields, values that are out of allowed ranges, incorrectly formatted data, or other validation failures.
+
+Common validation issues include:
+- Missing required fields
+- Values that exceed minimum or maximum limits
+- Strings that don't match required patterns
+- Invalid formats for IDs, emails, or other structured data
+- Type mismatches (e.g., providing a string where a number is expected)
+
+Here's an example of a request that would trigger this error:
+
+```bash
+# Attempting to create a rate limit with an invalid limit value of 0
+curl -X POST https://api.unkey.com/v2/ratelimit.limit \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
+  -d '{
+    "namespace": "api.requests",
+    "identifier": "user_123",
+    "limit": 0,
+    "duration": 60000
+  }'
+```
+
+## How To Fix
+
+To fix this error, carefully review the error details provided in the response. The `errors` array contains specific information about what failed validation:
+
+1. Check the `location` field to identify which part of your request is problematic
+2. Read the `message` field for details about why validation failed
+3. Look at the `fix` field (if available) for guidance on how to correct the issue
+4. Modify your request to comply with the validation requirements
+
+Here's the corrected version of our example request:
+
+```bash
+# Corrected request with a valid limit value
+curl -X POST https://api.unkey.com/v2/ratelimit.limit \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
+  -d '{
+    "namespace": "api.requests",
+    "identifier": "user_123",
+    "limit": 100,
+    "duration": 60000
+  }'
+```
+
+## Common Mistakes
+
+- **Ignoring schema requirements**: Not checking the API documentation for field requirements
+- **Range violations**: Providing values outside of allowed ranges (too small, too large)
+- **Format errors**: Not following the required format for IDs, emails, or other structured data
+- **Missing fields**: Omitting required fields in API requests
+- **Type errors**: Sending the wrong data type (e.g., string instead of number)
+
+## Related Errors
+- [err:unkey:application:assertion_failed](./assertion_failed) - When a runtime assertion or invariant check fails
+- [err:unkey:application:protected_resource](./protected_resource) - When attempting to modify a protected resource

apps/docs/api-reference/errors-v2/unkey/application/protected_resource.mdx

@@ -0,0 +1,72 @@
+---
+title: "err:unkey:application:protected_resource"
+description: "Attempt to modify a protected resource"
+---
+
+
+```json Example
+{
+  "meta": {
+    "requestId": "req_2c9a0jf23l4k567"
+  },
+  "error": {
+    "detail": "The resource you are attempting to modify is protected and cannot be changed",
+    "status": 403,
+    "title": "Forbidden",
+    "type": "https://unkey.com/docs/api-reference/errors-v2/unkey/application/protected_resource"
+  }
+}
+```
+
+## What Happened?
+
+This error occurs when you attempt to modify or delete a resource that is marked as protected in the Unkey system. Protected resources have special status that prevents them from being changed or removed, typically because they are system resources, defaults, or otherwise critical to proper system operation.
+
+Common scenarios that trigger this error:
+- Attempting to delete a default API or workspace
+- Trying to modify system-created roles or permissions
+- Attempting to change protected settings or configurations
+- Trying to remove or alter resources that are required for system integrity
+
+Here's an example of a request that might trigger this error:
+
+```bash
+# Attempting to delete a protected default API
+curl -X DELETE https://api.unkey.com/v1/apis.deleteApi \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
+  -d '{
+    "apiId": "api_default_protected"
+  }'
+```
+
+## How To Fix
+
+Since protected resources are deliberately shielded from modification, the solution is usually to work with or around them rather than trying to change them:
+
+1. **Work with the protected resource**: Use the resource as-is and build your workflows around it
+2. **Create a new resource**: Instead of modifying a protected resource, create a new one with your desired configuration
+3. **Use alternatives**: Look for alternative ways to achieve your goal without modifying protected resources
+4. **Contact support**: If you believe you have a legitimate need to modify a protected resource, contact Unkey support
+
+For example, instead of deleting a protected API, you might create a new one:
+
+```bash
+curl -X POST https://api.unkey.com/v2/apis.createApi \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
+  -d '{
+    "name": "My Custom API"
+  }'
+```
+
+## Important Notes
+
+- Protected resources are designated as such for system stability and security reasons
+- Even with admin or owner permissions, protected resources typically cannot be modified
+- This protection is separate from permission-based restrictions and applies even to workspace owners
+- The protection status of a resource is not typically exposed in API responses until you try to modify it
+
+## Related Errors
+- [err:unkey:authorization:forbidden](../authorization/forbidden) - When an operation is not allowed for policy reasons
+- [err:unkey:authorization:insufficient_permissions](../authorization/insufficient_permissions) - When you lack permissions for an operation