Skip to main content
The DevTune API uses standard HTTP status codes and returns structured JSON error responses.

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

Cause: One or more query parameters failed validation. The message includes details about which parameters are invalid. Fix: Check the endpoint documentation for valid parameter values and formats.

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

Cause: The 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

Cause: The API key lacks the scope the endpoint requires, your plan does not include API access, or the API key does not have access to the requested project. For a missing scope, the message names the scope: 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

Cause: The resource (webhook, action, brand, etc.) does not exist in this project, or was deleted. Fix: Verify the resource ID in the URL, and take IDs from the project’s own lists. A project ID that doesn’t match the key returns 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

Cause: The endpoint has been retired. Fix: Call the replacement endpoint named in message.

429 Too Many Requests

Cause: You’ve exceeded the rate limit for your plan tier. Fix: Wait the seconds in Retry-After before retrying. See Rate Limits for details.

500 Internal Server Error

Cause: Something went wrong on our end. Fix: Read 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: Read details.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 Bearer prefix: 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 (or window on Positioning and Accuracy); dateFrom and dateTo return 400. 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: latestRun shows what the latest scheduled run collected on each platform, and lastSucceededAt when the platform last answered.