Guides

Errors

The standard error envelope and the status codes the Dorascribe API returns.

The Dorascribe API uses conventional HTTP status codes and returns a consistent JSON error envelope, so you can handle failures the same way everywhere.

Error envelope

Failed requests return success: false with a human-readable error. Validation failures additionally include a field-keyed errors object:

JSON

{
  "success": false,
  "error": "The given data was invalid.",
  "errors": {
    "callback": ["Callback URL must use HTTPS"]
  }
}

Status codes

Status	Meaning	Common cause
`400 Bad Request`	Malformed request	e.g. a non-HTTPS callback URL
`401 Unauthorized`	Invalid or missing credential	Wrong API key or access token
`402 Payment Required`	Insufficient credits	Not enough credits for the tier or transcription
`403 Forbidden`	Not permitted for this organization	Wrong billing model, or a token with no transcriptions left
`422 Unprocessable Entity`	Validation failed	See the `errors` object for field details

Handling tips

Check success before reading a response body, rather than relying on the status code alone.
Surface errors fields back to the user on 422 — they're keyed by field name and are safe to display.
Treat 402 as a billing signal. Prompt the user to top up credits or review their billing model rather than retrying.
Verify callback signatures. A callback whose signature doesn't match should be rejected with 401 — see Widget integration.

Per-endpoint error responses are listed in the API Reference.