Error Response Format
All errors follow this structure.reason and details provide additional facts when available:
Each endpoint’s reference page lists the reasons it can return.
Read
details.retryable before retrying: API v2 5xx and 429 responses provide it, and a permanent refusal can be false even on a 5xx. Retryable 429 and 503 responses give Retry-After in seconds from the provider’s retry time or limiter reset, falling back to 60 seconds for 429 and GitHub throttles or 30 seconds for other 503 responses; GitHub secondary limits wait at least 60 seconds. MCP retry hints appear in JSON content as details.retryable and details.retryAfterSeconds; HTTP-level 429 and retryable 503 responses also include Retry-After. In code mode, a failed operation’s hint is in its failedOperations[].details; details at the top level of the result applies to the execution itself, such as a refused execution.
Error Codes
400 Bad Request
402 Payment Required
Cause: The request would spend credits the account doesn’t have.details can say how many more credits are needed.
Fix: Buy a credit pack on Billing, or wait for the monthly allowance.
401 Unauthorized
Authorization header is missing, malformed, or contains an invalid key.
Fix: Ensure your request includes Authorization: Bearer dtk_live_... with a valid, active API key.
403 Forbidden
API key scope does not allow access to "<scope>" endpoints.
Fix: For a missing scope, open API Keys, click Scopes on the key and add the named scope, or create a key that has it. Each endpoint’s reference page names the scope it requires; see Scopes. For a plan refusal, upgrade to a Plus plan or higher. For a project refusal (API key does not have access to this project), use a key created for the project in the URL.
404 Not Found
403, not 404.
409 Conflict
Cause: The request conflicts with the resource’s current state: another change is in progress, the item has already moved on, or the change needs confirmation.reason names which.
Fix: Follow the endpoint’s reference for that reason. When details.retryable is true, retry the request.
410 Gone
message.
429 Too Many Requests
Retry-After before retrying. See Rate Limits for details.
500 Internal Server Error
details.retryable. If it is true, retry after a short delay. If it is false or the error persists, follow the refusal message or contact support.
503 Service Unavailable
Cause: A service DevTune depends on failed. Fix: Readdetails.retryable. If it is true, wait the seconds in Retry-After before retrying; otherwise follow the refusal message.
Troubleshooting Tips
- Getting 401 on every request? Check that you’re using the
Bearerprefix:Authorization: Bearer dtk_live_... - Getting 403 with a valid key? The key may lack the endpoint’s scope, or the project ID in the URL may not match the project the key was created for.
- Getting 400 on date parameters? The API doesn’t take date ranges. Use
windowDays(orwindowon Positioning and Accuracy);dateFromanddateToreturn400. See Fixed windows. - Getting 429 unexpectedly? Rate limits are per-minute. If you’re making many requests in a loop, add a short delay between calls.
- Visibility data looks stale? Check probe health before retrying a Visibility read:
latestRunshows what the latest scheduled run collected on each platform, andlastSucceededAtwhen the platform last answered.
Related Documentation
- Authentication - API key setup
- Rate Limits - Limits by plan tier
- Probe health - Which AI platforms DevTune probed successfully