07 / WHEN A REQUEST STOPS

Know what to do next.

Requests have row, byte and time ceilings, plus shared account allowances and rate/concurrency limits. Different keys, the Explorer and the SDK all use the same ledger. SQL, unrestricted field selection, bulk downloads and unbounded pagination are not supported.

INSPECT WITHOUT RUNNING A DATA QUERYHTTP

curl --fail-with-body "$ORIGINFOLD_API_URL/v1/data-usage" \
  --header "Authorization: Bearer $ORIGINFOLD_API_KEY"

THE SAME ACCOUNT LEDGERPYTHON

from originfold_sdk import Client

with Client.from_env() as client:
    print(client.usage())

The usage response shows used, remaining, reset_at and effective limits. The monthly anniversary applies even to annual billing. Unused capacity does not roll over. Founding benefits, when granted, appear in the effective general allowance; safety ceilings are unchanged. There are no automatic overage charges.

Error or status	Your next step
`API_KEY_INVALID · 401`	Check the API origin and key. Revoke an exposed key; do not paste it into support messages.
`DATA_ACCESS_DENIED · 403`	Check the dataset, Plan and account status. A new key cannot grant missing access.
`DATASET_VERSION_UNAVAILABLE · 409`	Refresh the catalogue and deliberately select the current version for a new query.
`INVALID_QUERY, FIELD_NOT_ALLOWED, HISTORY_NOT_ALLOWED · 422`	Use allowed fields, exact identifiers and an explicit range within the available history.
`CURSOR_INVALID · 422`	Start a new page sequence for the current account and unchanged query. Never edit the cursor.
`RATE_LIMITED, CONCURRENCY_EXCEEDED, QUERY_BUSY · 429`	Wait at least the Retry-After interval and reduce concurrent work.
`QUOTA_EXHAUSTED · 429`	Check remaining rows, bytes and requests. Reduce an oversized reservation or wait until reset; changing keys does not help.
`ROW_BUDGET_EXCEEDED, RESPONSE_BUDGET_EXCEEDED · 422`	Request fewer rows or fields and narrow the date range.
`QUERY_TIMEOUT · 504`	Narrow the request before a deliberate retry. The SDK has not retried it.
`Account suspension or review`	Read the account notice and use its appeal route or contact human support. Do not bypass the restriction with another account.
`COMMERCIAL_UNAVAILABLE, DATA_UNAVAILABLE, USAGE_UNAVAILABLE · 503`	Check account/service status and retain the request ID. Data or commercial authority may be paused, or accounting may need review. Contact support if it persists.
`CONNECTION_FAILED, RESPONSE_INVALID, RESPONSE_TOO_LARGE`	Check connectivity and the configured API origin. Keep any request reference. A lost response may already have consumed usage; there is no hidden retry.

HANDLE A FAILED REQUESTPYTHON

from originfold_sdk import Client, OriginFoldError

# Use the query built above. There is no automatic retry.
with Client.from_env() as client:
    try:
        page = client.query(query)
    except OriginFoldError as error:
        print(error.code, error.status, error.request_id)
        print("Wait before retrying:", error.retry_after)
        print("Current usage, when supplied:", error.usage)

For HTTP, add --include to inspect status, X-Request-Id and Retry-After headers, then read the JSON error code. Share only the error code, request ID and a redacted description with support. Do not share credentials or private result rows.

Successful repeated or retried pages each count again. Rejected queries do not consume successful-request, returned-row or response-byte allowance, but execution attempts can count in short rate windows. Check usage before deciding to retry a response lost in transit.