Errors

Skirre uses standard HTTP status codes and returns structured JSON error responses. Every error includes a machine-readable code and a human-readable message.

Error Format

All error responses follow the same structure:

text
{
  "error": {
    "code": "not_found",
    "message": "Index 'products' not found"
  }
}
ParameterTypeDescription
error.code requiredstringMachine-readable error code. Use this for programmatic error handling.
error.message requiredstringHuman-readable error description. May change between versions, so do not parse programmatically.

Error Codes

ParameterTypeDescription
invalid_request optional400The request is malformed: missing required fields, invalid filter syntax, validation failure, or document exceeds size limits.
unauthorized optional401Missing or invalid API key. Check that the Authorization header contains a valid Bearer token.
forbidden optional403The API key does not have permission for this operation. Search keys cannot perform write operations.
not_found optional404The requested index, document, or API key was not found.
conflict optional409A resource with this identifier already exists (e.g. duplicate index UID).
rate_limited optional429Too many requests. Wait and retry. See the Rate Limits page.
internal_error optional500An unexpected server error. If persistent, contact support.

Handling Errors

With the SDK

The SDK throws SkirreError with typed status and code properties:

text
import { Skirre, SkirreError } from '@skirre/sdk';

try {
  await idx.getDocument('nonexistent');
} catch (err) {
  if (err instanceof SkirreError) {
    switch (err.code) {
      case 'not_found':
        console.log('Document does not exist');
        break;
      case 'rate_limited':
        console.log('Too many requests, retrying...');
        break;
      default:
        console.log(err.message);
    }
  }
}

With HTTP

Check the HTTP status code first, then parse the JSON body for the error code:

text
const res = await fetch(url, { headers });

if (!res.ok) {
  const body = await res.json();
  console.error(body.error.code, body.error.message);
  // "not_found" "Index 'products' not found"
}