Errors
API error codes and handling.
Error Handling
All API errors return a consistent JSON envelope:
{
"error": {
"code": "error_code",
"message": "Human-readable description",
"details": {}
}
}Error Codes
| Code | HTTP Status | Description |
|---|---|---|
unauthorized | 401 | Missing or invalid API key |
forbidden | 403 | API key lacks required scopes |
not_found | 404 | Resource not found |
conflict | 409 | Slug already exists |
validation_error | 400 | Invalid request body |
invalid_json | 400 | Request body is not valid JSON |
has_questions | 400 | Category deletion requires question reassignment |
rate_limit_exceeded | 429 | Rate limit exceeded |
invalid_request | 400 | Missing required path parameters |
Validation Errors
When request body validation fails, the details field contains Zod-formatted errors:
{
"error": {
"code": "validation_error",
"message": "Invalid request body",
"details": {
"fieldErrors": {
"question": ["String must contain at least 1 character(s)"]
},
"formErrors": []
}
}
}SDK Error Types
import { ApiError, ValidationError, SdkError } from '@faq/sdk';
try {
await client.createQuestion({ question: '', answer: '' });
} catch (error) {
if (error instanceof ApiError) {
// Server returned an error response
console.error(error.status, error.message, error.data);
}
if (error instanceof ValidationError) {
// Client-side validation failed
console.error(error.message);
}
if (error instanceof SdkError) {
// Network or timeout error
console.error(error.message);
}
}