This reference covers how the GIFQ API throttles requests and how it reports errors, so your integration can retry cleanly and surface useful messages.
Rate limiting
Each API token is throttled at 10 requests per second. Tokens are independent — traffic on one integration does not affect another.
If a request lacks an X-Api-Token header, it falls back to IP-based throttling under the same limit. Authenticate every request from your application.
Exceeding the limit returns HTTP 429 with a Retry-After header indicating how many seconds to wait. Read the header and pause for that duration. Do not implement a custom backoff that ignores it.
Error model
Errors return a JSON body with a message field and status: "error". Failed order creations additionally return a request_id — keep it. If you need support, that ID is the fastest way for the team to find your exact request.
Status codes you'll see
200/201— success.400— malformed request, or an out-of-range pagination page. Restart from page 1 if pagination drifts out of range.401— missing or invalidX-Api-Token.422— an order or payout could not be created. Causes include validation errors, insufficient balance, or catalog drift (a product changed between read and order). Includes arequest_id.429— rate limited. Honor theRetry-Afterheader.
Pagination edge case
List endpoints use a page query parameter with an optional limit (default 10, max 20). Requesting a page beyond total-pages returns HTTP 400. Iterate until current-page equals total-pages, and restart from page 1 if you hit an out-of-range error.
Handling errors well
Use idempotency on orders. Pass a unique
referenceper order so a retry after a network blip doesn't double-charge.Respect
Retry-After. It's the contract for backing off cleanly under load.Log the
request_idon every422so support can trace failures fast.