Error Responses

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 status	Code	Meaning
`400`	`invalid_request`	A path parameter, query parameter, cursor, or request format was invalid
`401`	`unauthenticated`	The `Authorization` header is missing, malformed, unknown, expired, or revoked
`403`	`permission_denied`	The API key does not include the required read scope
`404`	`not_found`	The requested resource was not found in the API key’s organization
`429`	`rate_limited`	A pre-auth, key, organization, or endpoint rate limit was exceeded
`500`	`internal_error`	Duckie 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.

Guides

API Reference

Error Codes

Authentication Errors

Permission Errors

Not Found Errors

​Error Codes

​Authentication Errors

​Permission Errors

​Not Found Errors

Error Codes

Authentication Errors

Permission Errors

Not Found Errors