Error Handling

Learn how to handle errors gracefully when using the Kanva API.

Error Response Format

All errors follow a consistent format:

{
  "success": false,
  "error": "Human-readable error message"
}

HTTP Status Codes

Code	Meaning	Action
400	Bad Request	Fix the request format or parameters
401	Unauthorized	Check your API key
403	Forbidden	You don't have access to this resource
404	Not Found	The project or job doesn't exist
408	Request Timeout	Prediction took too long (use async mode)
429	Too Many Requests	You've hit the rate limit
500	Internal Server Error	Retry later or contact support

Common Errors

Invalid Input Features

{
  "success": false,
  "error": "Invalid input: missing required feature 'date'"
}

Solution: Ensure all required features are included and correctly named.

Type Mismatch

{
  "success": false,
  "error": "Type error: feature 'value' expected numeric, got string"
}

Solution: Check that feature values match the expected data types.

Array Length Mismatch

{
  "success": false,
  "error": "All input arrays must have the same length"
}

Solution: Ensure all feature arrays have equal lengths for batch predictions.

Retry Strategy

For transient errors (5xx, network issues), implement exponential backoff:

import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

session = requests.Session()
retries = Retry(
    total=3,
    backoff_factor=0.5,
    status_forcelist=[500, 502, 503, 504]
)
session.mount("https://", HTTPAdapter(max_retries=retries))

response = session.post(url, headers=headers, json=data)

Rate Limit Handling

When you receive a 429 error, check the Retry-After header:

if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 60))
    time.sleep(retry_after)
    # Retry the request

See Rate Limits for more details.