Errors

Every error response has the same shape. Branch on error.code; it never changes. The message says what is wrong and how to fix it, and is written so an assistant can correct its own request. doc_url links to the code's section on this page.

{
  "error": {
    "code": "validation_failed",
    "message": "1 problem in the request. Fix it and send it again.",
    "details": [
      {
        "path": "questions[0].correct",
        "question_id": "capital",
        "code": "out_of_range",
        "message": "quiz 'capital': correct is 4 but there are 4 options (valid: 0–3). correct is a 0-based index into options."
      }
    ],
    "doc_url": "https://sparka.io/docs/errors#validation_failed",
    "request_id": "req_01K7Q3W8Z9G5H2M4N6P8R0S2T4"
  }
}

Messages below are templates: the parts in italics are filled in for each request. When a response has a Retry-After header, wait that many seconds before trying again.

The error object

Fields of the error object
Field	Type	Description
`code` required	string	Stable machine-readable code; the canonical list with HTTP statuses is `contracts/errors.json`. One of `invalid_json`, `validation_failed`, `invalid_request`, `missing_credentials`, `invalid_credentials`, `not_signed_in`, `quota_exceeded`, `wrong_credential_type`, `secret_key_in_browser`, `csrf_failed`, `recent_auth_required`, `session_full`, `nickname_rejected`, `presentation_not_found`, `session_not_found`, `pin_not_found`, `question_not_found`, `key_not_found`, `grant_not_found`, `oauth_request_not_found`, `route_not_found`, `method_not_allowed`, `session_ended`, `idempotency_conflict`, `version_conflict`, `payload_too_large`, `rate_limited`, `internal_error`, `no_live_capacity`, `service_unavailable`.
`message` required	string	One or two sentences saying what is wrong, the valid values, and the fix.
`details`	array of object	Present for validation errors; every problem is reported at once.
`details[].path` required	string	Example `questions[2].correct`.
`details[].question_id`	string	Pattern `^[a-z][a-z0-9_-]{0,31}$`.
`details[].code` required	string	Example `out_of_range`.
`details[].message` required	string
`doc_url` required	string	Format uri. Example `https://sparka.io/docs/errors#validation_failed`.
`request_id` required	string	Pattern `^req_[0-9A-HJKMNP-TV-Z]{26}$`.
`limit`	string	One of `sessions_per_month`, `presentations`, `concurrent_live_sessions`, `keys`.
`used`	integer
`max`	integer
`resets_at`	string \| null	Format date-time.
`upgrade_url`	string	Format uri.
`retry_after_s`	integer	At least 0.

400 Bad Request

`invalid_json`

HTTP 400 · Fix the request before retrying

The request body is not valid JSON ({reason}). Send a JSON object with Content-Type: application/json.

`validation_failed`

HTTP 400 · Fix the request before retrying

{count} problem(s) in the request. Fix them and send it again.

Extra fields: details.

`invalid_request`

HTTP 400 · Fix the request before retrying

{reason}

401 Unauthorized

`missing_credentials`

HTTP 401 · Fix the request before retrying

This endpoint needs credentials. Send Authorization: Bearer {accepted}.

`invalid_credentials`

HTTP 401 · Fix the request before retrying

This key or token is unknown or has been revoked. Create a new key at https://sparka.io/account.

`not_signed_in`

HTTP 401 · Fix the request before retrying

You are not signed in. Sign in at https://sparka.io/sign-in and try again.

402 Payment Required

`quota_exceeded`

HTTP 402 · Fix the request before retrying

This account has reached its {plan} plan limit for {limit} ({used} of {max}). {reset_or_upgrade}

Extra fields: limit, used, max, resets_at, upgrade_url.

Limits: sessions_per_month, presentations, concurrent_live_sessions, keys.

403 Forbidden

`wrong_credential_type`

HTTP 403 · Fix the request before retrying

This endpoint does not accept a {given}. It accepts: {accepted}.

`secret_key_in_browser`

HTTP 403 · Fix the request before retrying

Secret keys must never be used in a deck or web page. Use the presentation ID to start sessions; see https://sparka.io/docs/decks

`csrf_failed`

HTTP 403 · Fix the request before retrying

This request could not be verified. Reload the page and try again.

`recent_auth_required`

HTTP 403 · Fix the request before retrying

For your security, sign in again (within the last 15 minutes) before doing this.

`session_full`

HTTP 403 · Fix the request before retrying

This session is full. Ask the presenter for help.

`nickname_rejected`

HTTP 403 · Fix the request before retrying

Please choose a different nickname.