Copy page

Getting Started

Error Handling & Status Codes

The Cineamo API uses standard HTTP status codes to indicate the success or failure of requests.

📊 HTTP Status Codes

✅ Success Codes (2xx)

• 200 OK - Request succeeded
• 201 Created - Resource successfully created
• 204 No Content - Request succeeded with no response body

❌ Client Error Codes (4xx)

• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Missing or invalid authentication
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource doesn't exist
• 422 Unprocessable Entity - Validation errors
• 429 Too Many Requests - Rate limit exceeded

🔥 Server Error Codes (5xx)

• 500 Internal Server Error - Server-side error
• 502 Bad Gateway - Gateway error
• 503 Service Unavailable - Service temporarily unavailable

Error Response Format

All error responses follow this JSON structure:

Code
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "request_id": "req_abc123"
  }
}

Error Response Fields

• code - Machine-readable error code
• message - Human-readable error message
• details - Additional error details (optional)
• request_id - Unique request identifier for support

Common Error Codes

Code	Description
AUTHENTICATION_REQUIRED	Missing authentication credentials
INVALID_TOKEN	Invalid or expired access token
INSUFFICIENT_PERMISSIONS	User lacks required permissions
RESOURCE_NOT_FOUND	Requested resource doesn't exist
VALIDATION_ERROR	Request validation failed
RATE_LIMIT_EXCEEDED	Too many requests
INTERNAL_ERROR	Server-side error

Handling Errors

Retry Strategy

For 5xx errors and 429 rate limit errors:

1. Wait before retrying (use exponential backoff)
2. Maximum 3 retry attempts
3. Include request_id when contacting support

Example Error Handling

Code
async function makeApiRequest(url) {
  try {
    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return await response.json();
  } catch (error) {
    console.error('API Error:', error);
    // Handle error appropriately
  }
}

Getting Help

If you encounter persistent errors, contact support with:

• The request_id from the error response
• The endpoint and HTTP method used
• Request timestamp
• Error message and code