Errors

HTTP status codes and error handling

Error Format

Errors return JSON with a detail field:

{
  "detail": "Invalid or missing API key."
}

Validation errors (422) include field-level details:

{
  "detail": [
    {
      "loc": ["body", "query"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Status Codes

Code	Meaning	Action
200	Success
401	Unauthorized	Check your API key and Authorization header
402	Payment Required	Insufficient credits. Purchase more or upgrade to API Pro
404	Not Found	Resource does not exist
422	Validation Error	Check request body for missing or invalid fields
429	Rate Limited	Back off and retry with exponential backoff
500	Internal Error	Retry after a brief delay. Contact support if it persists

Rate Limiting

On 429, implement exponential backoff:

import time
import requests

def search_with_retry(query, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.vaquill.ai/api/v1/research/search",
            headers={"Authorization": "Bearer vq_key_..."},
            json={"query": query}
        )
        if response.status_code == 429:
            time.sleep(2 ** attempt)
            continue
        return response
    raise Exception("Max retries exceeded")

Troubleshooting

401 but my key is correct

Include the Bearer prefix: Authorization: Bearer vq_key_.... The key alone is rejected.

402 after purchasing credits

Credit purchases may take a few seconds to reflect after the payment provider confirms. Retry after a moment.

422 validation error

Set Content-Type: application/json. Check the loc field in the response to find the problematic field.