Skip to main content
The Shelfforce API uses conventional HTTP status codes and returns structured error responses with machine-readable error codes.

Error response format

Error codes

401
Missing Authorization header or invalid format. Include your API key as Authorization: Bearer sf_live_....
401
API key not found, revoked, or expired. Verify in API Keys settings.
402
Not enough credits. Purchase more or upgrade your plan.
403
API key role lacks permission for this endpoint. See Authentication.
404
Resource does not exist or belongs to a different organisation.
422
Missing required fields or invalid values. Check the details field.
429
Rate limit exceeded. Wait for Retry-After seconds. See Rate Limits.
500
Unexpected server error. Safe to retry with backoff. Contact hey@shelfforce.ai if persistent.

Handling errors

  • 4xx — Client errors. Fix the request before retrying. Do not retry 401, 402, 403, or 422.
  • 429 — Rate limited. Wait for Retry-After, then retry with exponential backoff.
  • 5xx — Server errors. Safe to retry with exponential backoff.
Always check the code field for programmatic error handling rather than parsing the message string. Error messages may change, but codes are stable.