# Error Handling

> Learn how to handle API errors and implement robust error handling

Source: https://docs.trykintsugi.com/docs/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 errors 4xx · 7 codes Fix the request, then retry.

400 Bad Request

Invalid request data or parameters.

Common causes

Missing required fields Invalid data types Business logic violations

401 Unauthorized

Invalid or missing authentication.

Common causes

Missing API key Invalid API key Expired token

403 Forbidden

Insufficient permissions.

Common causes

No access to organization Admin-only endpoint

404 Not Found

Resource does not exist.

Common causes

Invalid ID Deleted resource Wrong organization

409 Conflict

Resource conflict.

Common causes

Duplicate creation State conflicts Concurrent modifications

422 Unprocessable Entity

Validation errors.

Common causes

Invalid field values Constraint violations Business rules

429 Too Many Requests

Rate limit exceeded.

Common causes

Over 10,000 requests per minute

Server errors 5xx · 2 codes Retry with backoff.

500 Internal Server Error

Unexpected server error.

Common causes

Database errors Unhandled exceptions System failures

503 Service Unavailable

External service unavailable.

Common causes

Third-party API failures Maintenance windows

## Common Error Messages

Authentication Errors

Missing API Key

Error Response

{
"detail": "API key is missing or empty."
}

Solution

Include your API key in the x-api-key header (lowercase with hyphens):

curl -H "x-api-key: your-api-key" \
-H "x-organization-id: your-org-id" \
https://api.trykintsugi.com/v1/tax/estimate

Important: Kintsugi requires both x-api-key and x-organization-id headers for authentication. This is API key authentication via headers, not bearer token authentication.

Invalid API Key

Error Response

{
"detail": "Unauthenticated request."
}

Solution

Verify your API key is correct

Check if the API key is active

Ensure you're using the organization API key, not a personal key

Organization Access Denied

Error Response

{
"detail": "User does not have access to the specified organization"
}

Solution

Ensure your API key has access to the organization specified in the x-organization-id header:

curl -H "x-api-key: your-api-key" \
-H "x-organization-id: your-org-id" \
https://api.trykintsugi.com/v1/tax/estimate

Your Organization ID can be found in the lower left-hand corner of the Kintsugi Platform dashboard after logging in.

Admin Access Required

Error Response

{
"detail": "Admin access required for this endpoint."
}

Solution

Use an admin-level API key for this operation. Admin endpoints require elevated permissions.

Validation Errors

Missing Required Fields

{
"detail": [
{
"type": "missing",
"loc": ["body", "external_id"],
"msg": "Field required",
"input": null
}
]
}

Solution: Include all required fields in your request

Invalid Field Values

{
"detail": [
{
"type": "enum",
"loc": ["body", "currency"],
"msg": "Input should be 'USD', 'CAD', 'EUR'...",
"input": "INVALID",
"ctx": {"expected": "one of USD, CAD, EUR..."}
}
]
}

## Common Error Messages

Solution: Use valid enum values as specified in the API documentation

Business Logic Violations

{
"detail": [
{
"type": "value_error",
"loc": ["body", "discount_amount"],
"msg": "'discount_amount' must be less than the 'amount'.",
"input": 100.00,
"ctx": {"error": "discount exceeds amount"}
}
]
}

Solution: Ensure your data follows business rules and constraints

## 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")
}
)
raise

Provide User-Friendly Error Messages

Transform technical errors into user-friendly messages:

## Error Handling Best Practices

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."

## Troubleshooting Common Issues

Authentication Issues

Missing API Key

Error: API key is missing or empty.

Solution: Ensure you're including both the x-api-key and x-organization-id headers in your requests:

curl -H "x-api-key: your-api-key" \
-H "x-organization-id: your-org-id" \
https://api.trykintsugi.com/v1/tax/estimate

Kintsugi uses API key authentication via headers (not bearer token). Both headers are required.

Invalid API Key

Error: Unauthenticated request.

Solution:

Verify your API key is correct

Check if the API key is active

Ensure you're using the organization API key, not a personal key

Validation Issues

Missing Required Fields

Error: Field required

Solution: Check the API documentation for required fields and ensure all are included in your request body.

Invalid Data Types

Error: Input should be 'USD', 'CAD', 'EUR'...

Solution: Use the correct data types and enum values as specified in the API documentation.

Resource Issues

Resource Not Found

Error: Resource not found

Solution:

Verify the resource ID is correct

Check if the resource belongs to your organization

Ensure the resource hasn't been deleted

Access Denied

Error: User does not have access to the specified organization

Solution: Ensure your API key has access to the organization specified in the x-organization-id header. Your Organization ID can be found in the lower left-hand corner of the Kintsugi Platform dashboard after logging in.

## Related Resources

Getting Started

API Reference

Support

---

Index of every page: https://docs.trykintsugi.com/llms.txt