Errors and troubleshooting

Separate transport errors from run outcomes. HTTP 200 can contain a terminal failed run; HTTP 202 is accepted work that has not finished.

Error envelope

Request failures use a JSON error object. Optional retry information is included when available.

json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "example-request-id",
    "retry_after": 30
  }
}

Do not match human-readable messages in application logic. Use the HTTP status and machine-readable code. Keep the request ID with your internal logs; do not log API secrets or entire scraped records unnecessarily.

HTTP status guide

Status	Meaning	Recommended response
400	Invalid action input, body, or idempotency header	Correct the request; do not retry unchanged.
401	Missing, invalid, revoked, or unverified credential	Check the key or sign in again.
402	Insufficient credits or an inadequate request budget	Check the available balance and `max_credits`.
403	Wrong credential type or missing workspace	Use an API key for execution and a session for key management.
404	Unknown action, run, or key in this workspace	Check the ID and account.
409	An idempotency key was reused with different work	Restore the original payload or use a new key for intentional new work.
429	Request, queue, or capacity limit	Honor `Retry-After`, then retry with the same idempotency key.
500 / 503	Server or configuration problem	Back off; preserve the request ID and original idempotency key.

A live call returned no records

Read status first. A queued run has no final output yet. A completed empty result is different from a failure and uses zero result credits. A failed run reports an error in its body and releases its remaining reservation.

If the run completed but a specific field is absent, check that action's projection and the source profile's visibility. The API omits unavailable fields instead of inventing values.

Credits appear unavailable

Some of the balance may be reserved for outstanding work. Read credits_reserved in the workspace and run responses. Cancellation of processing work is pending until settlement or lease recovery; it is not an immediate refund guarantee.

The same results keep returning

Reusing an idempotency key intentionally returns the same run. Separately, list actions currently have no pagination cursor. A new key creates new work but does not ask for the next page.

Before escalating

Record the action ID, run ID, request ID, time, HTTP status, and sanitized request shape. Exclude credentials and personal data that are not needed to reproduce the issue. Retry a small bounded request only after checking its previous run state.