Errors

A request error means the API refused the call. A job failure means the API accepted the transcription, but it later ended with status set to failed.

The error envelope

Every /v1 request error has the same shape:

{
  "error": {
    "code": "insufficient_minutes",
    "message": "Not enough minutes",
    "retryable": false,
    "action_url": "https://transcript1.com/dashboard/billing",
    "minutes_needed": 20,
    "minutes_remaining": 3
  }
}

Handle errors by code. Display message to the user; its wording may change. When retryable is true, the same request may succeed later.

Some errors add fields next to retryable:

Request errors

Requests from a browser that use a login cookie instead of a bearer credential are also checked for their origin. A request from another site returns 403 forbidden_origin. API calls with an Authorization header are not affected.

Every 429 response includes a Retry-After header with the number of seconds to wait. See Billing and limits for the limits themselves.

Retry a request

• Retry only when retryable is true: rate_limited, too_many_active_jobs, too_many_live_sessions, live_capacity, internal_error, service_unavailable, and topup_needs_user with reason pending or in_progress. Honor Retry-After when it is present and back off between attempts otherwise.
• When retrying POST /v1/transcriptions or POST /v1/topups, send the same Idempotency-Key header to avoid a second charge if the original request succeeded.
• Fix the request before sending it again for every other code.

Live transcription

POST /v1/live/sessions and the other live endpoints use the same envelope. invalid_request, unsupported_language, insufficient_minutes and email_not_verified apply to them as well, together with the live codes in the table above. Creating a session is not idempotent, so a retry after too_many_live_sessions or live_capacity creates a new session.

After the session exists, problems arrive on the WebSocket as error events and close codes, not as HTTP errors. See Live transcription for every event.

A live session that ends for a reason such as balance_exhausted or idle_timeout is not an error: it sends session.ended with an end reason and is saved. See End reasons.

Job failures

When a transcription ends with status set to failed, the object has error: { "code", "message" }. Failures can happen after the request returned, so read error when you poll or in the transcription.failed webhook. A failed translation sends a transcription.translation.failed webhook and never fails the transcript.

Failed and canceled transcriptions are never charged. Minutes that were taken for a transcription are returned when it fails or is canceled.