Troubleshooting

Most problems with the Elastio API come down to a handful of causes: the token, the tenant, filters, pagination, or timing. Work through the sections below. If you are still stuck, collect the details of the request and contact support.

Start with a health check

A quick call to the health check tells you whether the tenant and token are right before you debug anything else.

GET

/gateway/api/v1/health_checkCheck API health status

Try it →

cURL

curl -i "https://acme.app.elastio.com/gateway/api/v1/health_check" \
  -H "Authorization: Bearer $ELASTIO_TOKEN"

Python

import os, requests

BASE = "https://acme.app.elastio.com"
HEADERS = {"Authorization": f"Bearer {os.environ['ELASTIO_TOKEN']}"}

resp = requests.get(f"{BASE}/gateway/api/v1/health_check", headers=HEADERS, timeout=30)
print(resp.status_code, resp.text)

PowerShell

$Base = "https://acme.app.elastio.com"
$Headers = @{ Authorization = "Bearer $env:ELASTIO_TOKEN" }
Invoke-WebRequest -Uri "$Base/gateway/api/v1/health_check" -Headers $Headers -SkipHttpErrorCheck |
    Select-Object StatusCode, Content

401 Unauthorized

The API did not accept the token. Check that:

• The header is exactly Authorization: Bearer <token>, with a space after Bearer and no quotes or line breaks around the token.
• The environment variable is set in the shell or process that runs your code. echo ${#ELASTIO_TOKEN} should print a non-zero length.
• The token hasn’t expired or been revoked. A tenant admin can check its expires_at with GET /gateway/shared-services/v1/personal-access-tokens, and look for it with GET /gateway/shared-services/v1/personal-access-tokens/revoked.
• You are calling the tenant the token was issued in. Each token belongs to one tenant (its tenant_id).

If the token was lost or exposed, revoke it and issue a new one. See Authentication.

403 Forbidden

The token is valid, but not allowed to perform this operation:

• Missing scope. The token’s grants don’t cover the area of the API you are calling, or it has read where the operation needs write. Update the token’s grants with PATCH, or issue a token with the right scopes.
• Admin-only operation. Some operations, such as the personal access token endpoints, require a tenant admin.
• Console relay. In the API console, a 403 with "error": "Console proxy error" comes from the portal’s relay, not your tenant: the tenant host isn’t allowed. Check the tenant name.

Wrong tenant

Your base URL must be https://{tenant}.app.elastio.com, where {tenant} is the subdomain you use to sign in to the console. Symptoms of a wrong tenant include connection or DNS errors, unexpected 404s on every path, 401 with a token you know is valid, and results that don’t match what you see in the console. Copy the subdomain from your console’s address bar.

Empty or unexpected results

A 200 with an empty list is usually a filter problem, not an error.

• Filters combine. Every filter you add narrows the results. Remove filters one at a time to find the one that excludes everything.
• Check the values. Multi-value filters take comma-separated values from a fixed set, such as severity=critical,high or health=infected,at_risk. Values must match the spec exactly. Use the operation’s filters endpoint, such as GET /gateway/api/v2/assets/filters or GET /gateway/api/v2/incidents/filters, to see the values that apply to your tenant.
• Check defaults. Some filters have defaults you might not expect. GET /gateway/api/v2/incidents returns only open incidents unless you pass status=closed or status=all. GET /gateway/api/v2/assets includes attached volumes and disks as top-level rows unless you pass show_attachments=false.
• Check date ranges. Operations that require a date range, such as GET /gateway/api/v1/jobs (startDate, endDate) and GET /rbac/api/v1/audit-logs (start_date, end_date), return nothing outside it.
• URL-encode values. JSON filters such as tags and tokens that contain +, / or = must be URL-encoded. Let your HTTP client build the query string (params= in Python, --data-urlencode with curl -G).
• Cached data. Some /gateway/api/v1 responses report cached: true with an expiry in milliseconds. Data can lag briefly behind the console.

Pagination problems

• You only get the first page. Lists are paginated. Follow pagination.next_page_token or increase offset until you have every item. See Pagination.
• The token is ignored. Use the parameter name the operation expects: next_page_token, page_token or pageToken. Check the operation in the API reference.
• A page token stops working. Keep the same filters and sort on every page, and don’t store tokens for later. Start again from the first page.
• Too many requests. Use the largest page size the operation allows. For example, GET /gateway/api/v2/incidents accepts a limit of at most 20, while GET /gateway/integration/v2/alerts accepts a pageSize of up to 100.
• The loop never ends. Stop when the token is missing or null, when offset reaches the total, or when a page comes back empty.

Timeouts and server errors

• Set a client timeout on every request (the examples use 30 seconds) so a slow call can’t hang your job.
• Retry 5xx, 429 and network errors with exponential backoff and jitter. Don’t retry other 4xx errors unchanged. See Errors.
• Narrow heavy queries. Add filters or a smaller date range rather than asking for everything at once.
• In the API console, the relay waits up to 60 seconds for your tenant and answers 504 if it doesn’t respond. Run long requests from your own code.

Polling long-running work

Hunts, deployments and reports run in the background. Some operations that start background work return 202 Accepted, such as running a policy (POST /gateway/shared-services/v3/policies/{name}/run), generating a report (POST /gateway/reporting/v2/reports) or starting a cloud configuration sync. You then follow progress through jobs or the resource itself.

• Poll gently. Wait between checks and increase the interval as the work runs longer, for example 10 seconds, then 30, then a minute. Hunts on large assets can take a long time.
• Poll the narrowest thing. Check one job or resource by ID rather than listing everything.
• Prefer push over poll where you can. Webhooks and alerts can notify you when something happens.
• Back off on 429 and 5xx. A polling loop that ignores errors can make an outage worse.

See Jobs for job-specific details.

Collect details for support

When you contact support, include enough detail to find your request:

• The HTTP method and full path, including query parameters, for example GET /gateway/api/v2/incidents?status=open&severity=critical.
• Your tenant subdomain.
• The time of the request, with time zone (UTC preferred).
• The status code and the full response body.
• The request body for writes, with any secrets removed.
• What you expected to happen, and whether it worked before.
• The ID of the token (from the token list), if the problem is about permissions.

Caution

Never send your personal access token to support, paste it into a ticket, or include it in logs and screenshots. Remove the Authorization header from anything you share. If a token has been exposed, revoke it immediately.

In cURL, -v prints the request and response headers; redact the Authorization line before sharing the output.