Errors & limits
Handle API errors, rate limits, usage allowances, and pagination.
Error responses
| Status | Meaning | What to do |
|---|---|---|
401 | The API key is missing, invalid, expired, or revoked. | Create a new key in Settings → Connected Apps and send it as a bearer token. |
403 | Your account cannot use the feature or access the requested resource. | Check plan eligibility, feature allowances, and project access. |
404 | The project, crawl, or other resource is unavailable to this key. | Confirm the UID and list accessible projects or crawls again. |
409 | The resource is in a state that prevents this request. | Read the current resource state, then retry only when the operation is valid. |
422 | A request value, filter, or cursor is invalid. | Correct the request fields; do not alter a cursor returned by the API. |
429 | Too many requests were sent. | Wait for the Retry-After duration before retrying. |
503 | The service is temporarily unavailable. | Retry later with a bounded backoff. |
Respect Retry-After
On a 429 response, wait for the number of seconds in the Retry-After header before sending another request. Avoid immediate retries or parallel retry bursts.
Usage and feature allowances
Screpy evaluates account eligibility and feature allowances for each request. Before starting crawls or processing large datasets, use account to read the current plan limits, usage, and available features.
For an invalid or revoked key, return to Authentication. If a project-specific request fails, list projects again before retrying with a different UID.
Pagination
List endpoints that support pagination accept limit and cursor. The default limit is 50, and the maximum is 100.
- Use the
next_cursorreturned by the API to request the next page. - Treat the cursor as opaque: do not construct, edit, or reuse it for a different request.
- Stop when
next_cursorisnull.