All error responses follow a consistent JSON structure:
{
"data": null,
"error": {
"message": "Error description",
"code": 400
}
}
Human-readable error description
HTTP Status Codes
The Aya API uses standard HTTP status codes:
Success Codes (2xx)
Resource created successfully
Request succeeded with no response body
Client Error Codes (4xx)
Invalid request parameters or body
Missing or invalid authentication token
Authenticated but lacking permissions
Resource conflict (e.g., slug already taken)
Server Error Codes (5xx)
Service temporarily unavailable
Common Error Messages
Authentication Errors
{
"data": null,
"error": {
"message": "Unauthorized",
"code": 401
}
}
Validation Errors
{
"data": null,
"error": {
"message": "unsupported locale",
"code": 400
}
}
Permission Errors
{
"data": null,
"error": {
"message": "You do not have permission to edit this profile",
"code": 403
}
}
Resource Errors
{
"data": null,
"error": {
"message": "Profile not found",
"code": 404
}
}
Discussion Errors
{
"data": null,
"error": {
"message": "discussions are not enabled",
"code": 404
}
}
Story Errors
{
"data": null,
"error": {
"message": "This story is synced from an external source and cannot be edited directly.",
"code": 409
}
}
Rate Limiting Errors
{
"data": null,
"error": {
"message": "Rate limit exceeded. Try again in 60 seconds.",
"code": 429
}
}
Error Handling Best Practices
Always check the HTTP status code firstHandle errors based on the status code category:
- 4xx: Client error - fix the request
- 5xx: Server error - retry with exponential backoff
Example Error Handling
try {
const response = await fetch(url, options);
if (!response.ok) {
const error = await response.json();
switch (response.status) {
case 401:
// Redirect to login
window.location.href = '/login';
break;
case 403:
// Show permission error
alert(error.error.message);
break;
case 404:
// Show not found
alert('Resource not found');
break;
case 429:
// Retry after delay
await delay(60000);
return retry();
case 500:
// Retry with backoff
return retryWithBackoff();
default:
// Show generic error
alert(error.error.message);
}
throw new Error(error.error.message);
}
return await response.json();
} catch (error) {
console.error('API Error:', error);
throw error;
}
Debugging Tips
Check the Status Code
Identify whether it’s a client error (4xx) or server error (5xx)
Read the Error Message
The error.message field provides specific details about what went wrong
Validate Your Request
- Check required parameters
- Verify JSON formatting
- Ensure locale is supported
- Confirm authentication token is valid
Check Rate Limits
Look at the X-RateLimit-* headers in the response
Contact Support
If the error persists, contact support with the error details and request ID (from response headers)
