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)

Status Code	Error Type	Description	Common Causes
`400`	Bad Request	Invalid request data or parameters	Missing required fields, invalid data types, business logic violations
`401`	Unauthorized	Invalid or missing authentication	Missing API key, invalid API key, expired token
`403`	Forbidden	Insufficient permissions	User lacks access to organization, admin-only endpoint
`404`	Not Found	Resource does not exist	Invalid ID, deleted resource, wrong organization
`409`	Conflict	Resource conflict	Duplicate creation, state conflicts, concurrent modifications
`422`	Unprocessable Entity	Validation errors	Invalid field values, constraint violations, business rules
`429`	Too Many Requests	Rate limit exceeded	Exceeding 10,000 requests per minute limit

Server Errors (5xx)

Status Code	Error Type	Description	Common Causes
`500`	Internal Server Error	Unexpected server error	Database errors, unhandled exceptions, system failures
`503`	Service Unavailable	External service unavailable	Third-party API failures, maintenance windows

Common Error Messages

Authentication Errors

Missing API Key

Error Response
Solution

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

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
Solution

{
  "detail": "Unauthenticated request."
}

Organization Access Denied

Error Response
Solution

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

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
Solution

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

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

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:

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

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
Invalid Data Types

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

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
Access Denied

Error: Resource not foundSolution:

Verify the resource ID is correct
Check if the resource belongs to your organization
Ensure the resource hasn’t been deleted

Error: User does not have access to the specified organizationSolution: 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.

Getting Started

Guides

API Guides

Advanced

SDKs

Model Context Protocol (MCP)

Error Response Format

HTTP Status Codes

Common Error Messages

Authentication Errors

Validation Errors

Error Handling Best Practices

Troubleshooting Common Issues

​Error Response Format

​HTTP Status Codes

​Common Error Messages

​Authentication Errors

​Validation Errors

​Error Handling Best Practices

​Troubleshooting Common Issues

​Related Resources

Error Response Format

HTTP Status Codes

Common Error Messages

Authentication Errors

Validation Errors

Error Handling Best Practices

Troubleshooting Common Issues

Related Resources