Validation & retries

Use this guide when a submission fails validation, times out or needs reconciliation. Start with a producer key and a persisted payload.

Idempotent retries

Generate one Idempotency-Key for each logical submission and persist it with the job that produced the payload.

• Retrying an accepted payload with the same key returns 200 OK, the original runId, and replayed: true.
• Retrying a rejected payload with the same key returns 422 SUBMISSION_REJECTED with replayed: true and the original validation issues; it does not return a runId.
• Reusing the key with a different payload returns 409 IDEMPOTENCY_KEY_CONFLICT.

It is safe to retry a request after a timeout only when both the idempotency key and body remain unchanged.

Validation rules

The submission is checked against the definition's required intervals, series, outputs and bounds. Follow scheduling for coverage and deadlines. The submission reference lists request limits and validation rules.

A validation failure returns 422 SUBMISSION_REJECTED and stores no forecast values:

{
  "error": {
    "code": "SUBMISSION_REJECTED",
    "message": "The submission was rejected and no forecast values were stored.",
    "details": {
      "replayed": false,
      "issues": [
        {
          "deliveryDay": "2026-07-27",
          "path": "deliveryWindows.0.values",
          "code": "INCOMPLETE_DELIVERY_WINDOW",
          "message": "Delivery day 2026-07-27 requires exactly 96 points; received 95."
        }
      ]
    }
  },
  "requestId": "8d62a94a-4d08-4ee3-9d34-1b4f829be021"
}

Use path to associate an issue with a field and code for programmatic handling. Messages are intended for humans and may become more specific over time.

Inspect accepted submissions

List your source's accepted runs, newest first:

curl 'https://telescope.energy/api/v2/producer/submissions?limit=25' \
  -H "Authorization: Bearer $TELESCOPE_API_KEY"

limit defaults to 50 and accepts values from 1 through 200.

Retrieve an accepted run with its delivery windows and normalized values:

curl 'https://telescope.energy/api/v2/producer/submissions/m57abc123' \
  -H "Authorization: Bearer $TELESCOPE_API_KEY"

A missing, invalid, or foreign run ID returns 404 SUBMISSION_NOT_FOUND.

For historical reconciliation, use the provider history endpoint. It selects values your account had successfully submitted by a fixed acceptance-time cutoff.

Next steps

Check scheduling for time-grid rules and troubleshooting for HTTP errors.