Errors

All Voshi API errors share one JSON envelope:

{
  "id": "Ie4rR0r1d",
  "api": "api",
  "time": "2026-07-27T18:10:00+00:00",
  "error": "ValidationError",
  "message": "score must be between 0 and 1",
  "details": {}
}

idstring

A unique ID for this error occurrence. Include it when contacting support — it lets the Voshi team find the corresponding server-side report.

errorstring

The error class, matching the status code below.

messagestring

A human-readable description of what went wrong.

detailsobject

Structured extras, when the error has them.

note

The response format is content-negotiated on the Accept header: API clients sending Accept: application/json (or no preference) get the JSON envelope; a browser gets an HTML error page carrying the same report ID.

Status codes

Status	Error	When
401	AuthenticationError	Missing, malformed, invalid, or expired credentials — a bad API key, a suspended app, or a stale api.token.
403	NotAuthorized	Authenticated, but not allowed — e.g. an app data token used on another user's row.
404	Http404	The resource doesn't exist — or belongs to another app. Voshi deliberately doesn't distinguish these, so other apps' launches and grades can't be probed.
422	ValidationError	The request was understood but a value is invalid. The message says which — see the per-endpoint error tables.
500	ApiException	Something failed on Voshi's side. Retry, and report the error id if it persists.

warning

Validation failures return 422, not 400. If your HTTP client only treats 400 as a validation error, widen the check.

Errors that don't reach your code

Launch-time failures (draft app, broken callback URL, deleted location) happen before your endpoint is called: the user sees a Voshi error page with a report ID, and your app never hears about the launch. See errors on Voshi's side.

Grade sync failures are not HTTP errors

A grade submission whose LMS sync fails still returns 200 — the failure is reported in-band via sync_status: "failed" and sync_error, so you can retry by re-POSTing. See sync status and retries.