Help

Troubleshooting

Diagnose API errors and choose a safe recovery step.

Start with the HTTP status, error.code and requestId. Parse the code for programmatic handling; messages may become more specific over time.

Read an error response

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Missing required API scope: forecasts:read."
  },
  "requestId": "8d62a94a-4d08-4ee3-9d34-1b4f829be021"
}

details is optional. The same request ID is returned in X-Request-ID.

Common errors

Status / code	Likely cause	What to do
`401 UNAUTHORIZED`	Missing, expired or revoked key	Check the Bearer header and replace the key if needed
`401 INVALID_API_KEY`	Incomplete or invalid key payload	Copy a valid newly created key into your secret store
`401 UNSUPPORTED_API_KEY_SUBJECT`	Unsupported key identity	Create a new key in Get Forecasts or Submit Forecasts
`403 FORECAST_SOURCE_ACCESS_DENIED`	Provider access is inactive or the key cannot submit for this account	Check Submit Forecasts access and contact support if onboarding is incomplete
`403 INSUFFICIENT_SCOPE`	Key belongs to the wrong workspace profile	Use a customer key for forecast reads or a producer key for submissions
`404 FORECAST_NOT_PUBLISHED`	At least one requested current delivery day has no publication	Check the product horizon and requested days; request published days or wait for release
`404 SUBMISSION_NOT_FOUND`	Missing, invalid or another provider account's run ID	Use a `runId` returned to your provider account
`409 IDEMPOTENCY_KEY_CONFLICT`	A key was reused with a different body	Retry the original body or create a new key for a new logical submission
`422 SUBMISSION_REJECTED`	One or more intervals violate the contract	Inspect `details.issues`, fix all reported fields and submit under a new key
`422 DELIVERY_DAYS_OUTSIDE_OFFERING_HORIZON`	A current-forecast `start` and `horizon` reach outside the product horizon	Request days within the catalog horizon, or use the data endpoint for past delivery days
`422 GATE_CLOSURE_NOT_SUPPORTED`	Gate-relative selection on a product without a gate	Use `relativeTo=validTime` or a fixed `asOf`, according to your intended decision time
`422 FORECAST_RANGE_TOO_COMPLEX`	The requested historical page is too large	Reduce `limit`; contact support if one day still fails
Other `422`	Invalid or incompatible parameters	Check the endpoint reference; provide exactly one historical selection mode
`429 PLAYGROUND_RATE_LIMITED`	Dashboard playground allowance exhausted	Wait for the returned retry delay; reduce playground request frequency
`500` / `502`	Server or upstream failure	Retry reads with bounded exponential backoff; preserve the request ID if the problem persists

Retry without duplicating a submission

After a timeout or server error, retry a POST only with the same persisted body and idempotency key. Do not regenerate timestamps or keys on an uncertain retry. An accepted replay returns the original runId; a rejected replay returns the original issues.

Use bounded retries with backoff and jitter. Authentication, permission, validation and idempotency conflicts need corrective action rather than repeated identical requests. Follow Validation & retries for submission-specific details.

Limits and availability

The dashboard playground has a limit of 60 requests per minute with burst capacity 60. This is a playground limit, not a documented allowance for external API-key traffic.

Historical ranges span at most 366 local days; pages contain 1–8 complete days. Submission bodies are limited to 1 MiB (1,048,576 UTF-8 bytes) and 10,000 scalar forecast values across all timestamps, series and outputs. A body over the limit returns 413 SUBMISSION_TOO_LARGE; excess values return 422 TOO_MANY_VALUES or a SUBMISSION_REJECTED issue with that code. Error lists contain at most 100 issues; issueCount and issuesTruncated report omitted errors. Product horizons and output bounds come from the live catalog.

A successful historical response can contain unavailable days or intervals. Inspect the availability reason instead of retrying indefinitely. See historical response semantics.

Webhook delivery problems

Open the webhook in your dashboard to inspect its last response, payload and next retry. Start with the webhook troubleshooting table for signature errors, missing events, duplicates and data-fetch failures. A Delivered event means your receiver accepted it; check your own background worker if processing did not complete.

Support

Email support@telescope.energy for integration, access or onboarding help. Include:

the problem and UTC request time;
method, endpoint, HTTP status, error.code and requestId;
relevant product, forecast version, submission run or webhook event IDs;
a sanitized request and response when useful.

Never send API keys or signing secrets. Remove proprietary forecast values unless needed to explain the issue.

Account request limits

All API keys of an account share two independent budgets: Customer and Producer reads refill at 120 requests per minute with capacity for a burst of 30; submissions refill at 30 per minute with capacity for a burst of 20. These are continuously refilling token buckets, not fixed minute windows. Authorized requests still count if subsequent validation fails, and retries count too.

On 429 RATE_LIMIT_EXCEEDED, wait at least the number of seconds in Retry-After before retrying. Keep the same body and Idempotency-Key for a submission retry. Spread polling over time and avoid retry loops; request a higher limit if your integration needs sustained additional capacity.

Public API

Anonymous websites, demos, and public integrations