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.

Endpoint group	Limit
API endpoints	120 requests per minute per IP
Webhook endpoint (/webhooks/github)	60 requests per minute per IP

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

If Redis is unavailable, rate limiting fails open — requests are allowed through rather than rejected.

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 X-CSRF-Token header. The token is provided in the session. Requests without a valid CSRF token receive 403 Forbidden.

Session expiry

Sessions have a 7-day maximum age and a 30-minute inactivity timeout. 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