Errors
Error codes, response format, and handling guidance for the Desktop Insights API.
The API uses standard HTTP status codes and returns structured error responses.
Error response format
{
"error": {
"code": "not_found",
"message": "App with bundle ID 'com.example.nonexistent' not found",
"requestId": "req_abc123"
}
}
HTTP status codes
| Code | Meaning | When |
|---|---|---|
200 | OK | Request succeeded |
400 | Bad Request | Invalid parameters (e.g., missing required field, invalid format) |
401 | Unauthorized | Missing or invalid API key |
403 | Forbidden | Valid key but insufficient plan tier for this endpoint/feature |
404 | Not Found | App or resource not found |
422 | Unprocessable Entity | Valid syntax but semantically invalid (e.g., minVersion without technology) |
429 | Too Many Requests | Rate limit exceeded — check X-RateLimit-Reset header |
500 | Internal Server Error | Something went wrong on our end |
Error codes
| Code | Description |
|---|---|
invalid_request | Missing required parameters or invalid parameter format |
unauthorized | API key is missing, invalid, or expired |
forbidden | Your plan does not include access to this endpoint or feature |
not_found | The requested app or resource does not exist |
rate_limited | Too many requests — wait until X-RateLimit-Reset |
quota_exceeded | Monthly credit quota exhausted — upgrade plan or wait for reset |
invalid_parameter | A specific parameter has an invalid value |
batch_too_large | Batch request exceeds the maximum size for your plan |
internal_error | Server-side error — retry after a short delay |
Tier-gated features
Some features return 403 Forbidden if your plan doesn't include them:
| Feature | Required Plan |
|---|---|
include=security | Team |
include=compliance | Team |
| Activity endpoint | Team |
| SBOM endpoint | Team |
| Release notes | Team |
| Bulk data exports | Enterprise |
The error response will indicate which plan is required:
{
"error": {
"code": "forbidden",
"message": "The 'security' include module requires a Team plan or higher. Current plan: Pro.",
"requestId": "req_def456",
"requiredPlan": "team"
}
}
Retry guidance
| Error | Retry? | Action |
|---|---|---|
400 | No | Fix the request parameters |
401 | No | Check your API key |
403 | No | Upgrade your plan |
404 | No | Verify the app identifier |
429 | Yes | Wait until X-RateLimit-Reset timestamp, then retry |
500 | Yes | Retry with exponential backoff (1s, 2s, 4s, max 3 retries) |