Errors

The Silent Witness API uses conventional HTTP response codes to indicate success or failure of requests. Codes in the 2xx range indicate success, 4xx codes indicate client errors, and 5xx codes indicate server errors.

Error Response Format

All errors return a consistent JSON structure:

{
  "success": false,
  "error": "Human-readable error message"
}

For validation errors, additional details may be included:

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "field": "case_id",
    "message": "case_id is required"
  }
}

HTTP Status Codes

Success Codes

Code	Description
200	Request succeeded
201	Resource created successfully
204	Request succeeded, no content returned

Client Error Codes

Code	Description
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Invalid or missing API key
403	Forbidden - Valid API key but insufficient permissions
404	Not Found - Resource doesn't exist
409	Conflict - Resource already exists or state conflict
422	Unprocessable Entity - Validation error
429	Too Many Requests - Rate limit exceeded

Server Error Codes

Code	Description
500	Internal Server Error - Something went wrong on our end
502	Bad Gateway - Upstream service unavailable
503	Service Unavailable - Temporary overload or maintenance
504	Gateway Timeout - Upstream service timeout

Common Error Scenarios

Authentication Errors (401)

Missing API Key

{
  "success": false,
  "error": "API key is required"
}

Invalid API Key

{
  "success": false,
  "error": "Invalid API key"
}

Resolution: Verify your API key is correct and included in the X-API-Key header.

Validation Errors (400)

Missing Required Field

{
  "success": false,
  "error": "case_id is required"
}

Invalid Field Value

{
  "success": false,
  "error": "Invalid report type: invalid_type. Supported types: technical_report"
}

Resolution: Check the API documentation for required fields and valid values.

Not Found Errors (404)

Case Not Found

{
  "success": false,
  "error": "Case not found"
}

Report Not Found

{
  "success": true,
  "data": null
}

Note: Some endpoints return null data instead of 404 (Stripe-style behavior).

Resolution: Verify the resource ID is correct and you have access to it.

Permission Errors (403)

Access Denied

{
  "success": false,
  "error": "Access denied to this resource"
}

Resolution: Ensure your API key has access to the organization that owns the resource.

Rate Limit Errors (429)

Rate Limit Exceeded

{
  "success": false,
  "error": "Rate limit exceeded. Please retry after 60 seconds."
}

Resolution: Implement exponential backoff and respect the Retry-After header.

File Upload Errors (400)

File Too Large

{
  "success": false,
  "error": "File size exceeds maximum limit of 50MB"
}

Empty File

{
  "success": false,
  "error": "Empty files are not allowed"
}

Resolution: Ensure files are under 50MB and not empty.

Error Handling Best Practices

1. Check Response Status

const response = await fetch('/api/cases', {
  method: 'POST',
  headers: { 'X-API-Key': apiKey },
  body: JSON.stringify(data)
});

if (!response.ok) {
  const error = await response.json();
  console.error('API Error:', error.error);
  // Handle specific error types
}

2. Implement Retry Logic

For transient errors (5xx, 429), implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.ok) return response;

    // Don't retry client errors (except 429)
    if (response.status < 500 && response.status !== 429) {
      throw new Error(`Client error: ${response.status}`);
    }

    // Exponential backoff
    const delay = Math.pow(2, i) * 1000;
    await new Promise(r => setTimeout(r, delay));
  }

  throw new Error('Max retries exceeded');
}

3. Handle Rate Limits Gracefully

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After') || 60;
  console.log(`Rate limited. Retrying after ${retryAfter} seconds`);
  await new Promise(r => setTimeout(r, retryAfter * 1000));
  // Retry the request
}

4. Log Errors for Debugging

Include request details when logging errors:

console.error('API Error:', {
  endpoint: '/api/cases',
  method: 'POST',
  status: response.status,
  error: errorBody.error,
  requestId: response.headers.get('X-Request-ID')
});

Report Generation Errors

Report generation can fail for various reasons:

Error	Description	Resolution
No vehicle images	No damage photos uploaded	Upload vehicle damage photos before creating report
Biomechanics failed	Occupant data incomplete	Ensure occupants have age, gender, and position
Delta-V calculation failed	ML inference error	Check image quality and try again
Report timeout	Generation took too long	Retry the report creation

Check report status for error details:

curl "https://api.silentwitness.ai/api/reports/rpt_xyz789" \
  -H "X-API-Key: $API_KEY"

{
  "success": true,
  "data": {
    "id": "rpt_xyz789",
    "status": "failed",
    "progress": {
      "message": "Delta-V calculation failed: insufficient image quality"
    }
  }
}