Skip to main content
When a request cannot be completed, the Vook API returns a structured error response that tells you exactly what went wrong and how to fix it. Rather than guessing from an HTTP status code alone, you get a machine-readable error code, a human-readable message, and a request_id you can use to get help. Build your error-handling logic around these fields and your integration will be far more resilient.

​
Error Response Format

All error responses follow the same structure, regardless of the HTTP status code: 
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "request_id": "req_abc123"
  }
}
FieldTypeDescription
codestringA stable, machine-readable identifier for the error type
messagestringA human-readable description of what went wrong
request_idstringA unique ID for this request — include it when contacting support
For validation errors (422), the response also includes a details array that pinpoints which fields failed and why: 
{
  "error": {
    "code": "validation_error",
    "message": "The request body contains invalid fields.",
    "request_id": "req_def456",
    "details": [
      {
        "field": "name",
        "issue": "required field is missing"
      },
      {
        "field": "tags",
        "issue": "must be an array of strings"
      }
    ]
  }
}

​
Common Error Codes

Your request did not include a valid API key. This error occurs when:
  • The Authorization header is missing entirely
  • The key has been deleted or revoked from the Vook dashboard
  • The key value contains a typo or extra whitespace
How to fix it: Verify that your API key is correct and that you are passing it as Authorization: Bearer YOUR_API_KEY. Generate a new key in the Vook dashboard if necessary.
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "request_id": "req_abc123"
  }
}
Your API key is valid, but it does not have the required permissions to access this resource or perform this action. API keys can be scoped to specific resources or operations.How to fix it: Check the key’s permission scopes in the Vook dashboard. If you need broader access, create a new key with the required scopes or contact your account administrator.
{
  "error": {
    "code": "insufficient_permissions",
    "message": "Your API key does not have permission to perform this action.",
    "request_id": "req_bcd234"
  }
}
The resource you requested does not exist. This can happen when:
  • The ID in the URL path is incorrect or belongs to a different account
  • The resource was deleted before you made the request
How to fix it: Double-check the resource ID. If you’re building a workflow that may delete resources, handle 404 gracefully and treat it as a terminal state rather than retrying.
{
  "error": {
    "code": "not_found",
    "message": "The requested resource could not be found.",
    "request_id": "req_cde345"
  }
}
The request body was valid JSON, but one or more fields failed validation. Check the details array in the error response — it lists each offending field along with a description of the problem.How to fix it: Read through the details entries and correct the fields in your request body. Common causes include missing required fields, incorrect data types, or values that fall outside allowed ranges.
{
  "error": {
    "code": "validation_error",
    "message": "The request body contains invalid fields.",
    "request_id": "req_def456",
    "details": [
      {
        "field": "name",
        "issue": "required field is missing"
      }
    ]
  }
}
You have sent too many requests in a short period. Every 429 response includes a Retry-After header (in seconds) indicating how long to wait before your next request is accepted.How to fix it: Pause your requests for the duration specified in Retry-After, then resume. Implement exponential backoff in your retry logic to avoid hitting the limit again immediately. If you consistently hit rate limits, consider requesting a higher limit for your account.
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please slow down and retry after the indicated period.",
    "request_id": "req_efg567"
  }
}

# Check the Retry-After header on a 429 response
HTTP/2 429
Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1730462400
An unexpected error occurred on Vook’s side. This is not caused by anything in your request. It is typically transient and resolves on its own within seconds.How to fix it: Wait briefly and retry the request with exponential backoff. If the error persists for more than a few minutes, check the Vook status page. When contacting support, include the request_id from the error response.
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again or contact support.",
    "request_id": "req_fgh678"
  }
}

​
Handling Errors

Structure your API calls to branch on the HTTP status code first, then inspect error.code for specific handling. The examples below show a robust pattern for creating a resource: 
import httpx
import time

client = httpx.Client(
    base_url="https://api.vook.ai/v1",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
)

def create_item(name: str, max_retries: int = 3):
    delay = 1.0

    for attempt in range(max_retries):
        try:
            response = client.post("/items", json={"name": name})

            if response.status_code == 201:
                return response.json()["data"]

            error = response.json().get("error", {})
            code = error.get("code")
            request_id = error.get("request_id")

            if response.status_code == 401:
                raise ValueError(f"Authentication failed ({request_id}): check your API key.")

            elif response.status_code == 422:
                details = error.get("details", [])
                raise ValueError(f"Validation failed ({request_id}): {details}")

            elif response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", delay))
                print(f"Rate limited. Retrying in {retry_after}s…")
                time.sleep(retry_after)
                continue

            elif response.status_code >= 500:
                if attempt < max_retries - 1:
                    print(f"Server error ({request_id}). Retrying in {delay}s…")
                    time.sleep(delay)
                    delay *= 2  # exponential backoff
                    continue
                raise RuntimeError(f"Server error after {max_retries} attempts ({request_id}).")

            else:
                raise RuntimeError(f"Unexpected error {response.status_code} ({request_id}): {code}")

        except httpx.RequestError as exc:
            if attempt < max_retries - 1:
                time.sleep(delay)
                delay *= 2
                continue
            raise RuntimeError(f"Network error after {max_retries} attempts: {exc}") from exc

    return None
When reaching out to support@vook.ai, always include the request_id from the error response (or the X-Request-ID response header). This single value lets the support team locate your exact request in the logs and dramatically speeds up diagnosis.