Errors

Every error has a stable code. Use it in your code; the texts next to it are for people and can change.

Simple API (v1)#

Errors of /v1 requests use application/problem+json (RFC 9457):

{
  "type": "https://switchfile.io/docs/api/v1#errors-unsupported-pair",
  "title": "Unsupported pair",
  "status": 422,
  "code": "UNSUPPORTED_PAIR",
  "detail": "Converting txt to mp4 is not supported."
}

type links to the code on this page. Validation errors add errors with messages per field, for example {"to": ["Expected string"]}. Errors about one entry of a batch or archive add index, the position of that entry. QUOTA_EXCEEDED adds limit, scope and reset_at, see Limits.

Request errors#

Conversion errors#

A request can succeed while the conversion fails later. Then the conversion has "status": "failed" and an error with code and message. With Accept: application/octet-stream and wait, the request itself returns the error as problem JSON.

Failed conversions use no credits and do not count toward the free daily quota.

Jobs and tasks (v2)#

Errors of /v2 requests are JSON in the format of the CloudConvert API v2:

{
  "message": "Task convert-1: output_format is required.",
  "code": "INVALID_DATA",
  "errors": {
    "tasks.convert-1.output_format": ["output_format is required."]
  }
}

Task errors#

A failed task has "status": "error" with code and message. If one task fails, the tasks that depend on it fail with INPUT_TASK_FAILED, and the job ends with error.

A failed task can be run again with POST /v2/tasks/{id}/retry.

What to retry#