Errors

PermitCore returns an RFC 9457 application/problem+json body for every non-2xx response:

{
  "type": "https://docs.permitcore.io/errors/missing-credentials",
  "title": "Missing Credentials",
  "status": 401,
  "detail": "Missing Authorization: Bearer <key> header.",
  "instance": "/v1/permits",
  "request_id": "req_1f07fb45782b445e9f6312ba23921234"
}

Branch your error handling on type (a stable URI), not on title or detail (human-readable, may change). status mirrors the HTTP status; instance is the request path; request_id also appears as the x-request-id response header — include it in support requests.

Error catalog

The type URI ends in the slug shown below; each links to a page explaining the error and how to fix it.

401 Unauthorized

`type` slug	Cause	Retry?
`missing-credentials`	`Authorization` header absent	No — fix client and resubmit
`invalid-credentials`	Key is malformed, revoked, or unknown	No — rotate key via dashboard

Auth is checked before the resource, so a bad key returns invalid-credentials even on an unknown path or jurisdiction.

403 Forbidden

`type` slug	Cause	Retry?
`insufficient-scope`	Key is valid but lacks the scope required for this endpoint	No — request a key with the needed scope
`tier-restricted`	Endpoint or query parameter requires a higher subscription tier	No — upgrade tier or remove parameter

404 Not Found

`type` slug	Cause	Retry?
`not-found`	Path or resource doesn’t exist, OR the jurisdiction is DEPLOY-PENDING	No — verify slug + endpoint

429 Too Many Requests

`type` slug	Cause	Retry?
`monthly-requests-quota-exceeded` / `daily-requests-quota-exceeded`	Quota exhausted (see Rate limits)	Yes — respect `Retry-After` header
`burst_limited`	Per-second burst threshold exceeded (future, Bucket 2)	Yes — exponential backoff

When Retry-After is large (multiple hours), the quota has been exhausted for the period. Bring the key up a tier or wait for the period to reset (monthly quotas reset on the first of each month UTC).

5xx Server errors

Retry 5xx on the HTTP status (below) with exponential backoff — don’t branch on the type slug for server errors.

HTTP	Cause	Retry?
`500`	Unexpected pipeline issue	Yes — exponential backoff, alert oncall after 3 retries
`502`	API gateway can’t reach origin	Yes — exponential backoff
`503`	Origin marked unhealthy	Yes — exponential backoff
`504`	Upstream took too long	Yes — exponential backoff

Retry guidance

Retryable status codes: 429 (respect Retry-After), 500, 502, 503, 504. All 4xx codes other than 429 are application errors and should NOT be retried — fix the request and resubmit.

Node.js

const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);

class PermitcoreError extends Error {
  constructor(status, type, detail) {
    super(detail);
    this.status = status;
    // Stable identifier to branch on — e.g. ".../errors/invalid-credentials".
    this.type = type;
  }
}

async function callPermitcore(path) {
  const res = await fetch(`https://api.permitcore.io${path}`, {
    headers: {
      Authorization: `Bearer ${process.env.PERMITCORE_API_KEY}`,
      Accept: "application/json",
    },
  });
  if (!res.ok) {
    // RFC 9457 problem+json: { type, title, status, detail, instance, request_id }
    const body = await res.json().catch(() => ({}));
    throw new PermitcoreError(res.status, body?.type, body?.detail);
  }
  return res.json();
}

async function withRetries(fn, maxAttempts = 4) {
  let lastErr;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      lastErr = err;
      const retryable = err instanceof PermitcoreError && RETRYABLE_STATUS.has(err.status);
      if (!retryable || attempt === maxAttempts) throw err;
      const delay = Math.min(2 ** attempt * 1000, 30000);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
  throw lastErr;
}

// Usage:
const data = await withRetries(() => callPermitcore("/v1/jurisdictions/nyc/cohorts/distribution"));

Diagnosing in production

Every response includes a x-request-id header (UUID). Include it in any support ticket — we can trace per-request.
Vercel deploy logs surface [cohort-distribution] <slug>: <error_type> for any caching layer failures.
For programmatic monitoring, the future /v1/keys/{prefix}/usage endpoint includes a recent_requests array with per-request status.

Introduction

Concepts

API Reference

Reference

Error catalog

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

5xx Server errors

Retry guidance

Diagnosing in production

​Error catalog

​401 Unauthorized

​403 Forbidden

​404 Not Found

​429 Too Many Requests

​5xx Server errors

​Retry guidance

​Diagnosing in production

Error catalog

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

5xx Server errors

Retry guidance

Diagnosing in production