Error Handling

Learn about error responses and how to handle them in the deadend.ai API.

Error Response Format

All errors follow a consistent structure:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "param": "parameter_name",
    "details": {}
  }
}

HTTP Status Codes

Common Error Codes

• invalid_api_key - The API key provided is invalid (401)
• insufficient_permissions - API access not available (403)
• invalid_request - Missing or invalid parameters (400)
• validation_error - Parameter validation failed (400)
• not_found - Resource doesn't exist (404)
• rate_limit_exceeded - Rate limit exceeded (429)
• internal_error - Internal server error (500)
• service_unavailable - Service temporarily unavailable (503)

Error Response Examples

Rate Limit Exceeded (429 Too Many Requests)

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "retryAfter": 60,
    "limit": 60,
    "remaining": 0,
    "reset": 1698672000
  }
}

Invalid API Key (401 Unauthorized)

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid"
  }
}

Plan Not Set (403 Forbidden)

{
  "error": {
    "code": "insufficient_permissions",
    "message": "API access not available. Please upgrade your plan."
  }
}

This error occurs when rate limits are exceeded or API access is restricted.

Invalid Request (400 Bad Request)

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: path",
    "param": "path"
  }
}

Validation Error (400 Bad Request)

{
  "error": {
    "code": "validation_error",
    "message": "Invalid page ID format",
    "param": "pageId",
    "details": {
      "value": "invalid-id"
    }
  }
}

Not Found (404 Not Found)

{
  "error": {
    "code": "not_found",
    "message": "Page not found",
    "resource": "Page",
    "id": "507f1f77bcf86cd799439011"
  }
}

Internal Error (500 Internal Server Error)

{
  "error": {
    "code": "internal_error",
    "message": "Failed to process search query",
    "requestId": "a1b2c3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6"
  }
}

Error Handling Best Practices

When handling errors from the API:

1. Check HTTP Status Codes: Use status codes to determine error types
2. Parse Error Response: All errors follow the standardized format with code, message, and optional param fields
3. Handle Rate Limits: When receiving 429 Too Many Requests, check the retryAfter field and wait before retrying
4. Don't Retry Client Errors: Don't retry on 4xx errors (except 429), as these indicate issues with the request itself
5. Log Errors: Log error details for debugging, but don't expose sensitive information to end users
6. Graceful Degradation: Handle errors gracefully without breaking your application flow

Next Steps

• Authentication - Learn about API keys
• Search API - Use the search endpoints
• Pages API - Manage your indexed pages