API Error Handling

The DevTune API uses standard HTTP status codes and returns structured JSON error responses.

Error Response Format

All errors follow this structure:

{
  "error": "error_code",
  "message": "Human-readable description of the error.",
  "status": 400
}

Field	Description
`error`	Machine-readable error code (e.g., `unauthorized`, `bad_request`)
`message`	Human-readable explanation
`status`	HTTP status code

Error Codes

400 Bad Request

{
  "error": "bad_request",
  "message": "Invalid query parameters: ...",
  "status": 400
}

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.

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key",
  "status": 401
}

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

{
  "error": "forbidden",
  "message": "API access requires a Plus plan or higher",
  "status": 403
}

Cause: Either your plan does not include API access, or the API key does not have access to the requested project. Fix: Upgrade to a Plus plan or higher. If you already have a qualifying plan, verify the API key is scoped to the correct project.

Note: A 403 can also occur when using a project-scoped API key to access a different project’s resources.

404 Not Found

{
  "error": "not_found",
  "message": "The requested resource was not found",
  "status": 404
}

Cause: The resource (project, webhook, etc.) does not exist or the API key does not have access to it. Fix: Verify the resource ID in the URL. If using a project-scoped key, ensure the project ID matches the key’s scope.

429 Too Many Requests

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later.",
  "status": 429
}

Cause: You’ve exceeded the rate limit for your plan tier. Fix: Wait until the X-RateLimit-Reset timestamp (in the response headers) before retrying. See Rate Limits for details.

500 Internal Server Error

{
  "error": "internal_error",
  "message": "An unexpected error occurred",
  "status": 500
}

Cause: Something went wrong on our end. Fix: Retry after a short delay. If the error persists, contact support.

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 project ID in the URL must match the project the key was created for.
Getting 400 on date parameters? Dates must be in YYYY-MM-DD format (e.g., 2026-01-15).
Getting 429 unexpectedly? Rate limits are per-minute. If you’re making many requests in a loop, add a short delay between calls.

Authentication - API key setup
Rate Limits - Limits by plan tier

Overview

Endpoints

API Error Handling

Error Response Format

Error Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

Troubleshooting Tips

​Error Response Format

​Error Codes

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​429 Too Many Requests

​500 Internal Server Error

​Troubleshooting Tips

​Related Documentation

Error Response Format

Error Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

Troubleshooting Tips

Related Documentation