Errors & Rate Limits

Fotobots enforces rate limits to ensure platform stability and equitable resource distribution across all events.

---

Rate Limit Headers

Every HTTP response includes standard rate limit metadata:

Header	Description
RateLimit-Limit	The maximum number of requests allowed in the current time window.
RateLimit-Remaining	The number of remaining requests allowed before throttling.
RateLimit-Reset	Time in seconds until the current rate limit window resets.

---

Standard Error Envelope

When a request fails, the API returns a standardized JSON error response:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "albumId is required and must be a valid UUID",
    "details": {
      "field": "albumId"
    }
  }
}

Common Error Codes

Status Code	Error Code	Meaning & Recommended Resolution
400	BAD_REQUEST	Validation failed. Check required parameters and Zod schema.
401	UNAUTHORIZED	Invalid or missing x-api-key header.
403	FORBIDDEN	API Key lacks permission scope for this action.
429	RATE_LIMITED	Request threshold exceeded. Implement exponential backoff.
500	INTERNAL_ERROR	Server exception. Contact support if the issue persists.