Error Handling

The LocalStitch API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error Response Format

All error responses follow this structure:

json

{
  "error": "error_code",
  "message": "Human readable description of the error"
}

Validation Errors

Validation errors include a details object with field-specific messages:

json

{
  "error": "validation_error",
  "message": "Invalid request parameters",
  "details": {
    "query": "Query string is required",
    "filters.rating_min": "Must be between 1 and 5"
  }
}

HTTP Status Codes

Code	Status	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`202`	Accepted	Async job created (e.g., enrichment)
`400`	Bad Request	Invalid parameters or request body
`401`	Unauthorized	Invalid or missing API key
`402`	Payment Required	Insufficient credits for operation
`403`	Forbidden	API access not available on your plan
`404`	Not Found	Resource not found
`409`	Conflict	Resource already exists (e.g., duplicate)
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error
`502`	Bad Gateway	Search service temporarily unavailable

Error Codes

The error field contains a machine-readable code:

Error Code	HTTP	Description
`unauthorized`	401	Invalid or missing API key
`api_access_denied`	403	API access requires a paid plan
`validation_error`	400	Invalid request parameters
`insufficient_credits`	402	Not enough credits for this operation
`not_found`	404	Requested resource doesn't exist
`duplicate`	409	Resource already exists
`rate_limited`	429	Too many requests, slow down
`search_error`	502	Search service error, retry later

Handling Errors in Code

Here's a recommended pattern for handling API errors:

javascript

400">"text-purple-400">async 400">"text-purple-400">function localstitchRequest(url, options) {
  400">"text-purple-400">const response = 400">"text-purple-400">await fetch(url, options);
  400">"text-purple-400">const data = 400">"text-purple-400">await response.json();
  
  400">"text-purple-400">if (!response.ok) {
    switch (response.status) {
      case 400:
        console.error(400">'Validation error:', data.details);
        break;
      case 401:
        console.error(400">'Check your API key');
        break;
      case 402:
        console.error(400">'Insufficient credits:', data.message);
        break;
      case 429:
        400">"text-purple-400">const retryAfter = response.headers.get(400">'Retry-After');
        console.error(400">`Rate limited. Retry after ${retryAfter}s`);
        break;
      400">"text-purple-400">default:
        console.error(400">'API error:', data.message);
    }
    throw new Error(data.message);
  }
  
  400">"text-purple-400">return data;
}

Best Practices

✓

Always check status codes

Don't assume success — verify response.ok or status codes.

✓

Log error details

Include the error code and message in your logs for debugging.

✓

Handle specific errors

Differentiate between recoverable errors (429, 502) and permanent ones (401, 403).

✓

Retry transient errors

Use exponential backoff for 429 and 5xx errors, but not for 4xx client errors.

PreviousPagination

NextCredits