Advanced
Error Handling
Error Response Format
All Kintsugi API errors follow a consistent JSON format:
{
"detail": "Error message describing what went wrong"
}For validation errors (422), the response includes detailed field-level information:
{
"detail": [
{
"type": "missing",
"loc": ["body", "external_id"],
"msg": "Field required",
"input": null
}
]
}HTTP Status Codes
Client errors4xx · 7 codesFix the request, then retry.
400Bad Request
Invalid request data or parameters.
Common causes
Missing required fieldsInvalid data typesBusiness logic violations
401Unauthorized
Invalid or missing authentication.
Common causes
Missing API keyInvalid API keyExpired token
403Forbidden
Insufficient permissions.
Common causes
No access to organizationAdmin-only endpoint
404Not Found
Resource does not exist.
Common causes
Invalid IDDeleted resourceWrong organization
409Conflict
Resource conflict.
Common causes
Duplicate creationState conflictsConcurrent modifications
422Unprocessable Entity
Validation errors.
Common causes
Invalid field valuesConstraint violationsBusiness rules
429Too Many Requests
Rate limit exceeded.
Common causes
Over 10,000 requests per minute
Server errors5xx · 2 codesRetry with backoff.
500Internal Server Error
Unexpected server error.
Common causes
Database errorsUnhandled exceptionsSystem failures
503Service Unavailable
External service unavailable.
Common causes
Third-party API failuresMaintenance windows
Common Error Messages
Authentication Errors
Validation Errors
Error Handling Best Practices
Implement Proper HTTP Status Code Handling
Check the response status code and handle each type appropriately:
import requests
try:
response = requests.get(url, headers=headers)
response.raise_for_status()
except requests.exceptions.HTTPError as e:
if e.response.status_code == 401:
# Handle authentication error
print("Invalid API key")
elif e.response.status_code == 429:
# Handle rate limiting
retry_after = e.response.headers.get('Retry-After', 60)
print(f"Rate limited. Retry after {retry_after} seconds")
elif e.response.status_code == 422:
# Handle validation errors
errors = e.response.json()['detail']
for error in errors:
print(f"Validation error: {error['msg']}")Implement Exponential Backoff
For rate limiting and temporary errors, implement exponential backoff:
import time
import random
def make_request_with_retry(url, headers, max_retries=3):
for attempt in range(max_retries):
try:
response = requests.get(url, headers=headers)
response.raise_for_status()
return response
except requests.exceptions.HTTPError as e:
if e.response.status_code == 429:
# Exponential backoff with jitter
wait_time = (2 ** attempt) + random.uniform(0, 1)
time.sleep(wait_time)
continue
else:
raise
raise Exception("Max retries exceeded")Log Errors Appropriately
Log errors with sufficient context for debugging:
import logging
logger = logging.getLogger(__name__)
try:
response = requests.get(url, headers=headers)
response.raise_for_status()
except requests.exceptions.HTTPError as e:
logger.error(
"API request failed",
extra={
"status_code": e.response.status_code,
"url": url,
"response_body": e.response.text,
"organization_id": headers.get("x-organization-id")
}
)
raiseProvide User-Friendly Error Messages
Transform technical errors into user-friendly messages:
def handle_api_error(error):
if error.response.status_code == 401:
return "Please check your API key and try again."
elif error.response.status_code == 404:
return "The requested resource was not found."
elif error.response.status_code == 422:
return "Please check your input data and try again."
elif error.response.status_code == 429:
return "Too many requests. Please wait a moment and try again."
else:
return "An unexpected error occurred. Please try again later."