Documentation

Errors

HTTP errors contain an `error` object with `code`, `message` and, when relevant, `parameter`.

Statuses and codes

Status	Code	Action
400	INVALID_QUERY	Fix malformed, repeated or unknown parameters
400	CONFLICTING_FILTERS	Resolve mismatched continent, nationality or city
400	UNSUPPORTED_VALUE	Choose a supported country or city
429	RATE_LIMITED	Wait for Retry-After
503	RESPONSE_TOO_LARGE	Lower count or select fewer fields

Handle rate limits

The default limit is 30 requests per minute per IP per instance. A 429 response includes Retry-After in seconds. Wait at least that long before retrying.

if (response.status === 429) {
  const seconds = Number(response.headers.get('Retry-After') ?? 1);
  await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
}

Other responses

Unknown routes return 404 and unsupported methods return 405. A response over 256 KiB returns 503 with RESPONSE_TOO_LARGE.

Try /people