Troubleshooting

Each entry points to the error code you will see in errors[].extensions.code. For the full code list, see
Error handling.

I get a 401 or "credentials could not be validated"

Code: UNAUTHORIZED

Confirm you are sending HTTP Basic authentication with your Shop ID as the username
and your API token as the password.
Check the Authorization header is present and correctly Base64-encoded
(base64(shopId:token)).
Confirm you are using HTTPS, not HTTP.
Verify the token has not been rotated or revoked. If in doubt, contact PayRetailers.

My credentials work but no data comes back

Code: MERCHANT_ID_MISSING

Your credentials are valid but could not be resolved to an active merchant account.
Confirm your Shop ID and API token belong to the correct, active shop.
Run query { currentMerchantId } to see which merchant your credentials resolve to.
If it still fails, contact support and quote the traceId from the error.

I get "access to the requested resource is denied"

Code: FORBIDDEN

All queries are automatically scoped to your merchant account.
Confirm the identifiers you are querying (transaction, claim, operation) belong to your
shop. You cannot query another shop's or merchant's data.

My page-size request is rejected

Code: PAGE_SIZE_EXCEEDED

The first argument must be 5000 or fewer.
Lower first and page through results using the after cursor.
If you omit first, a default page size of 1000 is applied.

My date range is rejected

Code: DATE_WINDOW_EXCEEDED or INVALID_DATE_RANGE

Most datasets allow a maximum window of 90 days; movement balances allow 31
days. Narrow the range or split it into several queries.
For INVALID_DATE_RANGE, ensure createdDateFrom is not later than createdDateTo
(also check editedDate and processedDate pairs).
To fetch one specific record without a date window, use a pinpoint filter such as
transactionId, claimId, or operationId.

My query is nested too deeply

Code: QUERY_DEPTH_EXCEEDED

Reduce query nesting to 10 levels or fewer.
Request fewer nested fields per query, and split work across several queries if needed.

Pagination stops working partway through

Code: CURSOR_EXPIRED

Cursors are valid for 4 hours. If a pagination run takes longer, cursors expire.
Restart from the first page (omit after) and page through within the 4-hour window.
Complete long exports faster by narrowing filters so each page returns quickly.

My cursor is rejected as invalid

Code: INVALID_CURSOR

Pass the exact endCursor value from the previous page's pageInfo as after.
Do not modify, truncate, decode, or construct cursor values. Treat them as opaque
tokens.

My queries fail intermittently under load

Codes: MERCHANT_CONCURRENCY_LIMIT_EXCEEDED, GLOBAL_CONCURRENCY_LIMIT_EXCEEDED,
TOO_MANY_REQUESTS (all retryable)

You may run up to 10 queries at once per merchant. Reduce parallelism.
Use a bounded worker pool or semaphore so no more than ~8 queries are in flight.
On these errors, back off (exponential backoff) and retry the same request.

My query times out

Code: QUERY_TIMEOUT (retryable)

Queries must complete within 15 seconds.
Make the query more selective: narrow the date range, add filters, or reduce the page
size.
A more targeted query returns faster; you may retry after adjusting the request.

I get a temporary data or service error

Codes: DATABRICKS_ERROR, SERVICE_UNAVAILABLE (both retryable)

These are temporary problems retrieving your data or a temporary service outage.
Wait briefly and retry the same request with exponential backoff.
If it persists, contact support and quote the traceId.

Aggregations return an "invalid filter" error

Code: INVALID_FILTER

Only PAYINS, PAYOUTS, and CLAIMS can be aggregated.
MOVEMENTBALANCES and REPORTBALANCES are not aggregatable and return this error.
Also check your filter field names and value types against the filter input for the
query. See Data model reference.

I get an unexpected internal error

Code: INTERNAL_ERROR (not retryable)

This is not caused by your request.
If it continues, contact support and quote the traceId from the error so the issue
can be investigated.

General debugging checklist

Read errors[].extensions.code first; it is deterministic.
Check errors[].extensions.retryable before retrying.
Keep the traceId for support conversations.
Reproduce with the smallest possible query (narrow date range, small first).
Confirm connectivity with query { ping } and scope with query { currentMerchantId }.