Copy page

Using the API

Errors, Rate Limits & Quotas

Authentication

Every /v1 request must carry your API key as a bearer token:

Code
curl https://api.fruitstand.dev/v1/funds/SPY \
  -H "Authorization: Bearer YOUR_API_KEY"

Create and manage keys from your account in this portal. Keep keys server-side — treat them like passwords.

Status codes

Status	Meaning	When
200	OK	Success.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	Valid key, but no active subscription/plan on it. Pick a plan on Pricing.
404	Not Found	Unknown fund code (single-fund endpoints only — see batch behavior below).
422	Unprocessable Entity	Invalid parameter, or more than 100 codes in a batch request.
429	Too Many Requests	Per-minute burst or monthly quota exceeded (see below).
503	Service Unavailable	Data temporarily stale/empty, or the service is briefly unavailable.

Error response shapes

Gateway policy errors (401, 403, 429) follow RFC 7807 problem+json:

Code
{
  "type": "https://httpproblems.com/http-status/429",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "You have exceeded your rate limit.",
  "instance": "/v1/funds/SPY"
}

Application errors (404, 422, 503) return a simpler body:

Code
{ "detail": "Fund 'XYZ' not found." }

Rate limits & quotas

Two independent limits apply per plan — a per-minute burst and a monthly quota:

Plan	Burst (per minute)	Monthly quota
Free	100 / min	250 requests
Developer	100 / min	1,000 requests
Pro	250 / min	2,500 requests
Business	500 / min	10,000 requests

• Exceeding either returns 429. Back off and retry after a short wait for burst; a quota 429 clears at your next monthly cycle (or upgrade your plan).
• Each API call counts as one request — including a /batch call, no matter how many codes it carries. Batching is the most quota-efficient way to pull many funds (see below).
• Caching is allowed on every plan (Licensing) — cache results to keep your request volume well under quota.

Batch endpoints

POST /v1/trailing-returns/batch and POST /v1/calendar-returns/batch accept up to 100 codes per call:

• More than 100 codes → 422.
• Unknown or missing codes are silently omitted from the response array — a batch never returns 404. Compare the returned codes against what you asked for to detect misses.

Code
curl https://api.fruitstand.dev/v1/trailing-returns/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"codes": ["SPY", "QQQ", "NOTAREALTICKER"]}'
# → returns rows for SPY and QQQ only

Pagination

GET /v1/funds uses keyset (cursor) pagination:

• limit — page size, default 100, max 1000 (values above 1000 are capped).
• The response's next_cursor is an opaque value; pass it back as ?cursor= to get the next page. When next_cursor is null, you've reached the end.

Code
# first page
curl "https://api.fruitstand.dev/v1/funds?type=ETF&limit=500" -H "Authorization: Bearer YOUR_API_KEY"
# next page
curl "https://api.fruitstand.dev/v1/funds?type=ETF&limit=500&cursor=SPY" -H "Authorization: Bearer YOUR_API_KEY"