Errors & Troubleshooting

Overview

The Que API provides detailed error responses following the RFC 7807 Problem Details format. This makes it easy to identify what went wrong and how to fix it.

Every error response contains:

• title – human-readable summary of the problem
• status – HTTP status code
• code – machine-usable error keyword
• detail – specific explanation
• details (optional) – structured context (e.g., retry wait time)

You should always log the full error response to help with debugging.

Common Errors

400 — Bad Request

Your request was malformed or missing required fields.

{
  "type": "about:blank",
  "title": "bad_request",
  "status": 400,
  "code": "bad_request",
  "detail": "manifest_json is required when mode=server_measure"
}

401 — Unauthorized

The request did not include a valid API key.

{
  "title": "unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "invalid API key"
}

Solution: Pass your API key in the x-api-key header.

403 — Forbidden

Your API key lacks permission.

{
  "title": "forbidden",
  "status": 403,
  "detail": "you do not have permission to perform this action"
}

Solution: Verify you’re using the correct environment key and role.

422 — Unprocessable Entity

The asset or manifest could not be processed.

{
  "title": "verification failed",
  "status": 422,
  "code": "engine_verification",
  "detail": "verification failed"
}

429 — Too Many Requests

You’ve exceeded your rate limit.

{
  "title": "rate_limited",
  "status": 429,
  "detail": "try again in 5000 ms",
  "details": { "try_again_in_ms": 5000 }
}

Solution: Implement exponential backoff and respect the Retry-After or details.try_again_in_ms field.

500 / 503 / 504 — Server Errors

Error inside the Que service, or upstream timeout.

Debugging Checklist

1. Confirm your request matches the API schema.
2. Verify your API key is valid and active.
3. Check if the asset is a supported format.
4. Review error code for specific hints.
5. Respect retries and rate limits.
6. For persistent issues, gather request/response logs and file a support ticket.