API rate limits and errors

The Pullminder API enforces rate limits on all endpoints and returns structured JSON error responses. This page documents the limits, error format, and HTTP status codes you may encounter.

Rate limits

Rate limiting is per-IP using fixed-window counters backed by Redis.

When a client exceeds the limit, the API returns 429 Too Many Requests with the body rate limit exceeded.

Error response format

All API responses use a consistent JSON envelope.

Success:

{
  "ok": true,
  "data": "..."
}

Error:

{
  "ok": false,
  "error": "description of what went wrong"
}

The error field contains a human-readable description of the problem.

HTTP status codes

Code	Meaning
200	Success
400	Bad request — invalid parameters or malformed input
401	Unauthorized — missing or invalid session cookie
403	Forbidden — authenticated but insufficient permissions (e.g., not an org member), or missing CSRF token
404	Not found — resource does not exist
429	Too many requests — rate limit exceeded
500	Internal server error
503	Service unavailable — database or Redis is down

CSRF protection

All mutating requests (POST, PATCH, PUT, DELETE) to authenticated endpoints require a valid CSRF token header. The token is provided in the session. Requests without a valid CSRF token receive 403 Forbidden.

Session expiry

Sessions expire after a period of inactivity. Once a session expires, the API returns 401 Unauthorized and the user must re-authenticate via the GitHub OAuth flow.

Next steps

• Authentication — session-based auth via GitHub OAuth
• API endpoints — complete reference for all REST endpoints
• Webhooks — GitHub webhook integration details