Errors

The CalendarPipe REST API uses standard HTTP status codes. A 2xx status indicates success; a 4xx indicates a client-side problem you can correct; a 5xx indicates a problem on CalendarPipe or an upstream provider.

Status codes

Code	Meaning	When you see it
200	OK	A successful read.
201	Created	A new resource was created — for example, a hosted calendar or event.
204	No Content	A successful delete or cancel. The response body is empty.
400	Bad Request	The request payload is missing required fields, malformed, or fails validation.
401	Unauthorized	The Authorization header is missing, the API key is invalid, or the key has been revoked.
402	Payment Required	The endpoint requires a Pro plan and the account is on Free.
403	Forbidden	You are authenticated but not allowed to perform this action on this resource.
404	Not Found	The resource does not exist or is not owned by the authenticated account.
409	Conflict	The request conflicts with the current state of the resource (for example, a duplicate).
422	Unprocessable Entity	The request was well-formed but a referenced resource is in a state that cannot satisfy it.
500	Internal Server Error	Something failed inside CalendarPipe. Retry; if the error persists, contact support.
502	Bad Gateway	An upstream provider (Google, Microsoft, Apple) rejected the request or is unavailable.

Response shape

Errors return JSON with a consistent envelope:

{
  "error": "Bad Request",
  "message": "start_at must be before end_at"
}

Field	Description
error	A short label matching the HTTP status (Unauthorized, Not Found, etc.).
message	A human-readable description of what went wrong.
details	Optional. Additional structured context — for example, the offending field on a validation error.

A successful response never uses this shape. Always check the HTTP status code before parsing the body.

Common cases

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Missing, invalid, or revoked API key"
}

Check the Authorization header — the value must be Bearer <key> with no extra whitespace, and the key must not have been revoked. See API Keys.

402 Payment Required

Returned when an account on the Free plan calls a Pro-only endpoint:

{
  "code": "API_ACCESS_BLOCKED",
  "type": "api_disabled",
  "message": "Public API is not available on the Free plan. Upgrade to Pro for API access."
}

Upgrade the account on the Billing page to clear the error.

502 Bad Gateway

CalendarPipe could not reach the upstream provider (Google Calendar, Microsoft Graph, iCloud). The original error message is forwarded in message to help diagnose. These are usually transient — retry after a short delay.

Retries

5xx responses are safe to retry. 4xx responses indicate a problem with your request and will keep failing until the request changes. Use exponential backoff for retries to avoid amplifying transient issues.

Related

• API Keys — authentication and the Authorization header.
• API Reference — per-endpoint request and response details.