Skip to main content
Duckie API errors use a single JSON shape. 
{
  "error": {
    "code": "invalid_request",
    "message": "limit must be a positive integer",
    "request_id": "req_123"
  }
}
Always log request_id when you contact Duckie support about a failed API request.

​
Error Codes

HTTP statusCodeMeaning
400invalid_requestA path parameter, query parameter, cursor, or request format was invalid
401unauthenticatedThe Authorization header is missing, malformed, unknown, expired, or revoked
403permission_deniedThe API key does not include the required read scope
404not_foundThe requested resource was not found in the API key’s organization
429rate_limitedA pre-auth, key, organization, or endpoint rate limit was exceeded
500internal_errorDuckie could not complete the request

​
Authentication Errors

Missing or malformed authentication returns: 
{
  "error": {
    "code": "unauthenticated",
    "message": "Authorization header must be 'Bearer <api_key>'",
    "request_id": "req_123"
  }
}
Unknown, expired, or revoked keys return: 
{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid API key",
    "request_id": "req_123"
  }
}

​
Permission Errors

If a key is valid but lacks the required scope, the API returns: 
{
  "error": {
    "code": "permission_denied",
    "message": "API key does not have the required scope",
    "request_id": "req_123"
  }
}
Create a new key with the needed scope or update your integration to call only endpoints the key can access.

​
Not Found Errors

Detail endpoints return 404 not_found when the resource does not exist in the API key’s organization. This includes valid UUIDs that belong to another organization.