Authentication and rate limits

The Fiddle REST API uses API key authentication and applies per-minute rate limits to keep the service responsive for everyone.

Authenticate every request

Send your API key in the X-API-Key header:

curl https://fiddle.io/rest/api/v2/sales-orders \
  -H "X-API-Key: YOUR_API_KEY"

Requests are scoped to the account that owns the key, and they act as the user the key is assigned to.

Use X-API-Key, not Authorization: Bearer. The Authorization header only accepts a Fiddle session or OAuth access token, so an API key sent there won’t authenticate.

Problem	Response
No X-API-Key header	400 with {"error": "No token found"}
Invalid or revoked key	401 with {"error": "Invalid API key"}

Rate limits

Limits depend on whether the request carries an API key:

Request type	Limit
With an API key	100 requests/min per key
Without a key	20 requests/min per IP address

When you exceed the limit, the API returns 429 Too Many Requests. Wait before retrying.

Build in a small backoff: on a 429, pause briefly and retry. Spreading bulk jobs over time keeps you comfortably under the limit.

Handle errors

The API uses standard HTTP status codes:

Status	Meaning
200	Success
400	Invalid request body or parameters, a validation error, or no API key
401	Invalid or revoked API key
404	Record not found in your account
429	Rate limit exceeded

Most errors return a JSON body with an error message. Validation errors return an errors field that describes what to fix.

Always send requests over HTTPS. Keys sent over plain HTTP are exposed in transit.

Next steps

See common API recipes for ready-to-run examples.