Error classes
Everything the library throws extends PcoError, so err instanceof PcoError catches all of it.
A non-2xx response becomes a PcoApiError subclass chosen by status code, thrown after any retries.
PcoError
├── PcoApiError any non-2xx response
│ ├── PcoBadRequestError 400
│ ├── PcoAuthenticationError 401
│ ├── PcoForbiddenError 403
│ ├── PcoNotFoundError 404
│ ├── PcoConflictError 409
│ ├── PcoValidationError 422
│ ├── PcoRateLimitError 429
│ └── PcoServerError 5xx
├── PcoNetworkError no response (DNS failure, connection reset, ...)
├── PcoTimeoutError an attempt exceeded timeoutMs
├── PcoOAuthError code exchange, refresh, revoke, or introspect failed
└── PcoWebhookError webhook body already read
├── PcoWebhookVerificationError bad or missing signature (status 401)
└── PcoWebhookParseError malformed delivery (status 400)A plain PcoError is also thrown for invalid input before any request is sent: a missing or mixed
auth, an empty id, perPage(500), or an action the docs don’t list.
Every PcoApiError has:
| Property | Description |
|---|---|
status |
HTTP status code |
method, url |
The request that failed (the URL never contains credentials) |
errors |
The JSON:API errors array from the response |
hint |
Planning Center’s error hint, if the response had one (see below) |
headers |
Response headers |
body |
Parsed response body (or the raw text if it wasn’t JSON) |
message |
GET https://... failed with 404: Not Found plus details and hint |
import { PcoApiError, PcoNotFoundError } from '@mackenly/planningcenterkit';
try {
await pco.people.people.id('123').update({ nickname: 'Ada' });
} catch (err) {
if (err instanceof PcoNotFoundError) {
// the person was deleted
} else if (err instanceof PcoApiError) {
console.error(err.status, err.errors.map((e) => e.detail));
} else {
throw err;
}
}Validation errors
PcoValidationError.fieldErrors groups the messages by attribute (taken from each error’s
source.pointer; errors without a pointer are under base):
import { PcoValidationError } from '@mackenly/planningcenterkit';
try {
await pco.people.people.id('123').emails.create({ address: 'not an email' });
} catch (err) {
if (err instanceof PcoValidationError) {
console.log(err.fieldErrors); // { address: ['is invalid'] }
}
}Error hints
Planning Center tags some errors with an animal codename. The library finds it and sets hint,
and adds its meaning to the message. The full list is exported as PCO_ERROR_HINTS.
| Hint | Meaning |
|---|---|
BABOON |
The OAuth access token is expired |
CAPUCHIN |
The OAuth access token has been revoked |
PELICAN |
The OAuth token is missing a required scope |
CHINCHILLA |
The client application was not found or is invalid |
FLAMINGO |
The authenticated user does not exist |
LEMMING |
The authenticated organization does not exist |
TRASH_PANDA |
The person doesn’t have access to the requested product |
BLACKBIRD |
The request includes an unsupported kind parameter |
WEASEL, ANTEATER, BLUE_JAY, MOCKINGBIRD |
Signature authentication failures |
import { PcoAuthenticationError, PcoForbiddenError } from '@mackenly/planningcenterkit';
try {
await pco.services.service_types.list();
} catch (err) {
if (err instanceof PcoForbiddenError && err.hint === 'PELICAN') {
// ask the user to re-authorize with the `services` scope
} else if (err instanceof PcoAuthenticationError && err.hint === 'CAPUCHIN') {
// the user disconnected your app
}
}With OAuth auto-refresh configured, an expired token (BABOON) is refreshed and the request
replayed before you ever see the error.
Retries
| Situation | Retried? | Wait |
|---|---|---|
429 Too Many Requests |
Yes, any method (the request wasn’t processed) | Retry-After, or backoff if absent |
5xx |
GET and DELETE only |
Backoff (at least Retry-After if sent) |
| Network error or timeout | GET and DELETE only |
Backoff |
401 with OAuth refresh configured |
Once, after refreshing the token | None |
Any other 4xx |
No |
POST and PATCH aren’t retried on server or network errors because Planning Center may already
have applied them. Backoff is exponential with full jitter, starting at 500 ms and capped at 10 s.
const pco = new PlanningCenter({
auth,
retry: {
maxRetries: 3, // retries after the first attempt; 0 disables retrying
retryServerErrors: true, // retry 5xx/network/timeouts for GET and DELETE
maxRetryAfterSeconds: 60, // a 429 asking for longer throws PcoRateLimitError right away
},
});When retries run out, the last error is thrown (PcoRateLimitError, PcoServerError,
PcoNetworkError, or PcoTimeoutError). PcoRateLimitError.retryAfter has the seconds the API
asked for.
Rate limiting
Planning Center allows a fixed number of requests per window (by default 100 requests per 20
seconds per user) and reports the current window in X-PCO-API-Request-Rate-Limit,
-Count, and -Period headers. The client:
- Paces itself from those headers: once the window is used up, new requests wait for it to
reset instead of getting a
429. Turn it off withrateLimit: { throttle: false }. - Pauses everything after a
429, for theRetry-Afterit was given, so concurrent requests don’t pile on. - Limits concurrency to
maxConcurrencyrequests in flight (default10); the rest queue.
All products on one PlanningCenter share one transport, so these limits are coordinated across
pco.people, pco.services, and the rest. If you create several clients for the same
credentials, share a transport between them:
import { createTransport, PlanningCenter } from '@mackenly/planningcenterkit';
import { createGivingClient } from '@mackenly/planningcenterkit/giving';
const transport = createTransport({ auth: { applicationId: '...', secret: '...' } });
const pco = new PlanningCenter({ transport });
const giving = createGivingClient({ transport });Timeouts and cancellation
timeoutMs (default 30000) limits each attempt. A timed-out GET or DELETE is retried; when
retries run out, you get a PcoTimeoutError.
Pass an AbortSignal to cancel a request, including any retry or rate-limit wait:
const controller = new AbortController();
const pending = pco.people.people.toArray({ signal: controller.signal });
controller.abort();
await pending.catch((err) => console.log(err.name)); // 'AbortError'An abort rejects with the signal’s reason as-is (not wrapped in a PcoError), so
AbortSignal.timeout(5000) rejects with a TimeoutError DOMException.
Logging and telemetry
Hooks observe every attempt without changing it. They never receive credentials, and errors they throw are ignored.
const pco = new PlanningCenter({
auth,
hooks: {
onRequest: ({ method, url, attempt }) => console.debug(`-> ${method} ${url}${attempt ? ` (retry ${attempt})` : ''}`),
onResponse: ({ method, url, status, durationMs }) => console.debug(`<- ${status} ${method} ${url} ${durationMs}ms`),
onRetry: ({ reason, status, delayMs }) => console.warn(`retrying after ${reason} ${status ?? ''} in ${delayMs}ms`),
onThrottle: ({ delayMs }) => console.warn(`rate limit window full, waiting ${delayMs}ms`),
},
});| Hook | Called | Info |
|---|---|---|
onRequest |
Before each attempt | method, url, attempt (0 for the first) |
onResponse |
After each attempt that got a response | adds status, durationMs |
onRetry |
Before waiting to retry | adds delayMs, reason (rate_limit, server_error, network_error, timeout), status?, error? |
onThrottle |
When a request waits for the rate limit window | method, url, delayMs |
Other transport options
| Option | Default | Description |
|---|---|---|
userAgent |
Appended to the planningcenterkit User-Agent, e.g. my-app/1.0 |
|
headers |
Extra headers on every request | |
fetch |
global fetch |
Custom fetch (proxies, tests, instrumentation) |
baseUrl |
https://api.planningcenteronline.com |
API origin |
uploadUrl |
https://upload.planningcenteronline.com/v2/files |
File upload endpoint |