This document provides a comprehensive reference for all error codes and responses returned by the Yemaya API. The API uses RFC 7807 Problem Details for error responses.
Table of Contents#
- Error Response Format
- Client Errors (4xx)
- Server Errors (5xx)
- Custom Error Codes
- Validation Errors
- Error Handling Best Practices
Error Response Format#
All API errors follow the RFC 7807 Problem Details format:
{
"type": "https://api.yemaya.io/problems/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "Request validation failed",
"instance": "/v1/projects",
"requestId": "req_abc123xyz",
"timestamp": "2024-01-15T10:30:00.000Z",
"errors": [
{
"field": "email",
"message": "Invalid email format",
"code": "invalid_email"
}
]
}
Response Fields#
| Field | Type | Description |
|---|---|---|
type |
string | URI reference identifying the problem type |
title |
string | Short, human-readable summary of the problem |
status |
number | HTTP status code |
detail |
string | Human-readable explanation specific to this occurrence |
instance |
string | URI reference to the specific occurrence (request path) |
requestId |
string | Unique request identifier for support |
timestamp |
string | ISO 8601 timestamp of the error |
errors |
array | Validation errors (for validation failures) |
extensions |
object | Additional context-specific data |
Client Errors (4xx)#
400 Bad Request#
Type: https://api.yemaya.io/problems/bad-request
The request could not be understood by the server due to malformed syntax.
{
"type": "https://api.yemaya.io/problems/bad-request",
"title": "Bad Request",
"status": 400,
"detail": "The request body could not be parsed as JSON"
}
Common Causes:
- Malformed JSON in request body
- Invalid query parameters
- Missing required headers
- Invalid content encoding
400 Validation Error#
Type: https://api.yemaya.io/problems/validation-error
The request body failed schema validation.
{
"type": "https://api.yemaya.io/problems/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "Request validation failed",
"errors": [
{
"field": "email",
"message": "Invalid email format",
"code": "invalid_string"
},
{
"field": "password",
"message": "Password must be at least 8 characters",
"code": "too_small"
}
]
}
Common Validation Codes:
| Code | Description |
|---|---|
invalid_type |
Wrong data type provided |
invalid_string |
String format validation failed |
invalid_enum |
Value not in allowed enum list |
too_small |
Value below minimum length/size |
too_big |
Value above maximum length/size |
invalid_date |
Invalid date format |
required |
Required field is missing |
401 Unauthorized#
Type: https://api.yemaya.io/problems/unauthorized
Authentication is required or has failed.
{
"type": "https://api.yemaya.io/problems/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Invalid or expired access token"
}
Common Causes:
- Missing Authorization header
- Invalid or expired JWT token
- Invalid API key
- Token has been revoked
Headers Returned:
WWW-Authenticate: Bearer realm="api.yemaya.io"
403 Forbidden#
Type: https://api.yemaya.io/problems/forbidden
The authenticated user does not have permission to access the resource.
{
"type": "https://api.yemaya.io/problems/forbidden",
"title": "Forbidden",
"status": 403,
"detail": "You do not have permission to access this project",
"extensions": {
"requiredRole": "editor",
"currentRole": "viewer"
}
}
Common Causes:
- Insufficient role permissions
- Resource belongs to another user
- Organization-level restrictions
- Feature not available on current plan
404 Not Found#
Type: https://api.yemaya.io/problems/not-found
The requested resource could not be found.
{
"type": "https://api.yemaya.io/problems/not-found",
"title": "Not Found",
"status": 404,
"detail": "Project with ID 'prj_abc123' was not found",
"extensions": {
"resourceType": "project",
"resourceId": "prj_abc123"
}
}
Common Causes:
- Resource does not exist
- Resource has been deleted
- Incorrect resource ID format
- Resource belongs to a different organization
405 Method Not Allowed#
Type: https://api.yemaya.io/problems/method-not-allowed
The HTTP method is not allowed for this endpoint.
{
"type": "https://api.yemaya.io/problems/method-not-allowed",
"title": "Method Not Allowed",
"status": 405,
"detail": "POST method is not allowed on this endpoint",
"extensions": {
"allowedMethods": ["GET", "PATCH", "DELETE"]
}
}
Headers Returned:
Allow: GET, PATCH, DELETE
409 Conflict#
Type: https://api.yemaya.io/problems/conflict
The request conflicts with the current state of the resource.
{
"type": "https://api.yemaya.io/problems/conflict",
"title": "Conflict",
"status": 409,
"detail": "A user with this email already exists",
"extensions": {
"conflictingField": "email"
}
}
Common Causes:
- Duplicate unique field (email, username)
- Concurrent modification conflict
- Resource state prevents operation
- Version mismatch (optimistic locking)
410 Gone#
Type: https://api.yemaya.io/problems/gone
The resource is no longer available and will not be available again.
{
"type": "https://api.yemaya.io/problems/gone",
"title": "Gone",
"status": 410,
"detail": "This resource has been permanently deleted"
}
Common Causes:
- Resource was permanently deleted
- API endpoint has been deprecated and removed
413 Payload Too Large#
Type: https://api.yemaya.io/problems/payload-too-large
The request entity is larger than the server will process.
{
"type": "https://api.yemaya.io/problems/payload-too-large",
"title": "Payload Too Large",
"status": 413,
"detail": "Request body exceeds maximum size of 10MB",
"extensions": {
"maxSize": 10485760,
"receivedSize": 15728640
}
}
Limits:
| Endpoint | Maximum Size |
|---|---|
| General API | 10 MB |
| File uploads | 100 MB |
| Batch operations | 50 MB |
415 Unsupported Media Type#
Type: https://api.yemaya.io/problems/unsupported-media-type
The request content type is not supported.
{
"type": "https://api.yemaya.io/problems/unsupported-media-type",
"title": "Unsupported Media Type",
"status": 415,
"detail": "Content-Type 'text/plain' is not supported",
"extensions": {
"supportedTypes": ["application/json", "multipart/form-data"]
}
}
422 Unprocessable Entity#
Type: https://api.yemaya.io/problems/unprocessable-entity
The request was well-formed but could not be processed.
{
"type": "https://api.yemaya.io/problems/unprocessable-entity",
"title": "Unprocessable Entity",
"status": 422,
"detail": "Cannot delete a project with active collaborators"
}
Common Causes:
- Business logic validation failed
- Operation not allowed in current state
- Semantic errors in request
429 Rate Limited#
Type: https://api.yemaya.io/problems/rate-limited
Too many requests have been made.
{
"type": "https://api.yemaya.io/problems/rate-limited",
"title": "Too Many Requests",
"status": 429,
"detail": "Rate limit exceeded. Please retry after 60 seconds",
"extensions": {
"limit": 1000,
"remaining": 0,
"resetAt": "2024-01-15T10:31:00.000Z"
}
}
Headers Returned:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705318260
Retry-After: 60
Rate Limits:
| Tier | Requests per Minute |
|---|---|
| Free | 60 |
| Pro | 1000 |
| Enterprise | 10000 |
Server Errors (5xx)#
500 Internal Server Error#
Type: https://api.yemaya.io/problems/internal-error
An unexpected error occurred on the server.
{
"type": "https://api.yemaya.io/problems/internal-error",
"title": "Internal Server Error",
"status": 500,
"detail": "An unexpected error occurred",
"requestId": "req_xyz789"
}
What to Do:
- Note the
requestIdfor support - Retry the request after a short delay
- Contact support if the error persists
501 Not Implemented#
Type: https://api.yemaya.io/problems/not-implemented
The server does not support the functionality required.
{
"type": "https://api.yemaya.io/problems/not-implemented",
"title": "Not Implemented",
"status": 501,
"detail": "This feature is not yet implemented"
}
502 Bad Gateway#
Type: https://api.yemaya.io/problems/bad-gateway
The server received an invalid response from an upstream server.
{
"type": "https://api.yemaya.io/problems/bad-gateway",
"title": "Bad Gateway",
"status": 502,
"detail": "Error communicating with upstream service"
}
503 Service Unavailable#
Type: https://api.yemaya.io/problems/service-unavailable
The server is temporarily unable to handle the request.
{
"type": "https://api.yemaya.io/problems/service-unavailable",
"title": "Service Unavailable",
"status": 503,
"detail": "Service is temporarily unavailable for maintenance",
"extensions": {
"retryAfter": 300
}
}
Headers Returned:
Retry-After: 300
504 Gateway Timeout#
Type: https://api.yemaya.io/problems/gateway-timeout
The server did not receive a timely response from an upstream server.
{
"type": "https://api.yemaya.io/problems/gateway-timeout",
"title": "Gateway Timeout",
"status": 504,
"detail": "Request timed out waiting for upstream service"
}
Custom Error Codes#
Quota Exceeded#
Type: https://api.yemaya.io/problems/quota-exceeded
A usage quota has been exceeded.
{
"type": "https://api.yemaya.io/problems/quota-exceeded",
"title": "Quota Exceeded",
"status": 402,
"detail": "Monthly AI generation quota exceeded",
"extensions": {
"quotaType": "ai_generations",
"limit": 1000,
"used": 1000,
"resetAt": "2024-02-01T00:00:00.000Z"
}
}
Resource Locked#
Type: https://api.yemaya.io/problems/resource-locked
The resource is locked by another user or process.
{
"type": "https://api.yemaya.io/problems/resource-locked",
"title": "Resource Locked",
"status": 423,
"detail": "This scene is currently being edited by another user",
"extensions": {
"lockedBy": "usr_xyz789",
"lockedAt": "2024-01-15T10:20:00.000Z",
"lockedUntil": "2024-01-15T10:35:00.000Z"
}
}
Feature Disabled#
Type: https://api.yemaya.io/problems/feature-disabled
A feature is disabled for the current user or organization.
{
"type": "https://api.yemaya.io/problems/feature-disabled",
"title": "Feature Disabled",
"status": 403,
"detail": "AI image generation is not available on your current plan",
"extensions": {
"feature": "ai_image_generation",
"requiredPlan": "pro"
}
}
External Service Error#
Type: https://api.yemaya.io/problems/external-service-error
An external service (AI provider, storage, etc.) returned an error.
{
"type": "https://api.yemaya.io/problems/external-service-error",
"title": "External Service Error",
"status": 502,
"detail": "AI service temporarily unavailable",
"extensions": {
"service": "openai",
"originalError": "rate_limit_exceeded"
}
}
Database Error#
Type: https://api.yemaya.io/problems/database-error
A database operation failed.
{
"type": "https://api.yemaya.io/problems/database-error",
"title": "Database Error",
"status": 500,
"detail": "A database error occurred. Please try again later.",
"requestId": "req_abc123"
}
Validation Errors#
Validation errors include detailed information about which fields failed validation:
{
"type": "https://api.yemaya.io/problems/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "Request validation failed",
"errors": [
{
"field": "name",
"message": "Name is required",
"code": "required"
},
{
"field": "email",
"message": "Must be a valid email address",
"code": "invalid_string"
},
{
"field": "age",
"message": "Age must be at least 18",
"code": "too_small"
}
]
}
Field Path Notation#
For nested objects, the field path uses dot notation:
{
"errors": [
{
"field": "address.zipCode",
"message": "Invalid zip code format",
"code": "invalid_string"
},
{
"field": "items[0].quantity",
"message": "Quantity must be positive",
"code": "too_small"
}
]
}
Error Handling Best Practices#
1. Always Check the Status Code#
const response = await fetch('https://api.yemaya.io/v1/projects');
if (!response.ok) {
const error = await response.json();
throw new Error(`${error.title}: ${error.detail}`);
}
2. Handle Specific Error Types#
async function handleApiError(error: ProblemDetails) {
switch (error.type) {
case 'https://api.yemaya.io/problems/unauthorized':
// Redirect to login
await refreshToken();
break;
case 'https://api.yemaya.io/problems/rate-limited':
// Wait and retry
const retryAfter = error.extensions?.retryAfter || 60;
await delay(retryAfter * 1000);
break;
case 'https://api.yemaya.io/problems/validation-error':
// Show field errors
displayFieldErrors(error.errors);
break;
default:
// Show generic error
showError(error.detail);
}
}
3. Log Request IDs#
Always log the requestId for debugging:
console.error(`API Error [${error.requestId}]: ${error.detail}`);
4. Implement Retry Logic#
async function fetchWithRetry(url: string, options: RequestInit, retries = 3) {
for (let attempt = 0; attempt < retries; attempt++) {
const response = await fetch(url, options);
if (response.ok) {
return response;
}
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After') || '60';
await delay(parseInt(retryAfter) * 1000);
continue;
}
if (response.status >= 500) {
await delay(Math.pow(2, attempt) * 1000); // Exponential backoff
continue;
}
// Client errors should not be retried
throw new Error(await response.text());
}
throw new Error('Max retries exceeded');
}
5. Display User-Friendly Messages#
const userFriendlyMessages: Record<string, string> = {
'https://api.yemaya.io/problems/unauthorized':
'Your session has expired. Please log in again.',
'https://api.yemaya.io/problems/rate-limited':
'You\'re making requests too quickly. Please slow down.',
'https://api.yemaya.io/problems/quota-exceeded':
'You\'ve reached your usage limit for this month.',
'https://api.yemaya.io/problems/service-unavailable':
'We\'re experiencing technical difficulties. Please try again later.',
};
function getErrorMessage(error: ProblemDetails): string {
return userFriendlyMessages[error.type] || error.detail;
}
Quick Reference#
| Status | Type | Description |
|---|---|---|
| 400 | bad-request | Malformed request syntax |
| 400 | validation-error | Request validation failed |
| 401 | unauthorized | Authentication required or failed |
| 403 | forbidden | Insufficient permissions |
| 404 | not-found | Resource not found |
| 405 | method-not-allowed | HTTP method not allowed |
| 409 | conflict | Request conflicts with current state |
| 410 | gone | Resource permanently deleted |
| 413 | payload-too-large | Request body too large |
| 415 | unsupported-media-type | Content-Type not supported |
| 422 | unprocessable-entity | Semantic validation failed |
| 429 | rate-limited | Too many requests |
| 500 | internal-error | Unexpected server error |
| 501 | not-implemented | Feature not implemented |
| 502 | bad-gateway | Upstream server error |
| 503 | service-unavailable | Temporary unavailability |
| 504 | gateway-timeout | Upstream server timeout |
Need Help?#
If you encounter an error that you cannot resolve:
- Check the
requestIdin the error response - Review your request parameters and authentication
- Check our status page for any ongoing issues
- Contact support at api@yemaya.io with the
requestId