Error Handling

Standard Error Format

All Calendi API errors follow a consistent JSON structure:

{
  "success": false,
  "error": "Descriptive error message",
  "details": "Additional context when available"
}

HTTP Status Codes

400 - Bad Request

Invalid request data or missing required parameters.

{
  "success": false,
  "error": "Missing required field: contact.email"
}

401 - Unauthorized

Invalid or missing API key.

{
  "success": false,
  "error": "Invalid API key"
}

404 - Not Found

Requested resource doesn't exist.

{
  "success": false,
  "error": "Event not found"
}

409 - Conflict

Resource conflict (e.g., no available seats, reservation expired).

{
  "success": false,
  "error": "No available seats for this time slot"
}

500 - Internal Server Error

Unexpected server error.

{
  "success": false,
  "error": "An internal error occurred. Please try again later."
}

Rate Limiting

When rate limits are exceeded, you'll receive a 429 status with these headers:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200

{
  "success": false,
  "error": "Rate limit exceeded. Try again later."
}

Best Practices

1. Always Check Success Field

if (!response.success) {
  console.error('API Error:', response.error);
  return;
}

2. Handle Rate Limits Gracefully

Implement exponential backoff when receiving 429 responses.

3. Validate Input Before API Calls

Reduce 400 errors by validating required fields client-side.

4. Monitor API Key Validity

Watch for 401 responses and refresh credentials when needed.

5. Implement Timeout Handling

Set appropriate timeouts for reservation operations to handle network issues.