Errors, limits and versions

Everything on this page holds for every endpoint of /v1: one handler on your side can read every refusal, and one retry policy covers every call.

One error shape

Whatever the status, an error answers the same body:

{
  "code": "not_found",
  "message": "no asset of this organization has this id",
  "request_id": "0192a6d3-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

• code is what your code branches on. A code keeps its meaning for good, and the list may grow: read a code you do not know by the HTTP status it came with.
• message is English, written for a person — log it, show it to a developer, never branch on it: it may change at any time.
• request_id identifies the request: quote it when you ask us about a failure. It is absent, never null, when the server has none to give.

Statuses and codes

The API reference lists, for each endpoint, the refusals it may answer.

A body refused: 415, 422 or 400

Every body is JSON, but a thumbnail’s, which is the picture itself. A body is refused for one of three reasons, and each has its status:

• 415 — it is not sent under the right Content-Type: a JSON body outside application/json, a thumbnail outside image/jpeg, image/png or image/webp;
• 422 — it is not the request: a required field is missing, a field has the wrong type, or the body names a field the request does not list;
• 400 — it is the request, but a value is refused by its rules: too long, malformed, contradicting another. The message names the field.

The API does not ignore what it does not understand: an unknown field in a body is refused rather than ignored, and so is a query parameter — one the endpoint does not list, or one given twice (400). ?typ=video is refused rather than served unfiltered, and a write takes no query parameter at all. A typo is an error you see at once, never a setting quietly ignored.

An identifier in a body: 404

An identifier sent in a body — a workspace, a channel, an asset, a custom field — that names nothing your key can reach is a 404, whether it names nothing at all or something of another organization’s. It is the same answer as for an identifier in the path.

A publication’s categories are the exception: a category that is not one of the publication’s channel is refused with a 400, which names it.

The 403s that are not a permission

A key carrying the right permission may still get a 403:

• the organization does not publish channels: every channel, category and publication endpoint answers 403 to all of its keys;
• the asset is validated in the organization’s shared pool: it is read-only to the API, and each of the requests that change it answers 403, whatever the key carries — only the pool’s moderators change it, from Videas. See Edit an asset.

Neither is retried.

The 409s

A 409 says the request contradicts the resource’s state. Reading that state again says what to do:

Retrying

• 429: wait the number of seconds Retry-After gives, then send the same request again.
• 500, 502, 503, 504: retry after a growing delay — an exponential back-off.
• A GET is always safe to send again, and so are a PATCH and a PUT: each says what the resource should hold, and sent twice, the second finds it holding that already and writes nothing.
• DELETE /v1/uploads/{upload_id} is safe to send again: an upload already given up on, expired or failed answers 204 and stays as it is.
• A POST creates something: after a timeout or a 5xx, look for what the first one may have created before sending it again.
  • POST /v1/uploads and POST /v1/assets are not idempotent: sent twice, they create two assets. Set external_ref every time, and look it up with GET /v1/assets?external_ref= before sending again — for a file as for a video hosted elsewhere.
  • POST /v1/publications publishes an asset once on a channel: sent again, it answers 409, and GET /v1/publications?channel_id=…&asset_id=… finds the publication the first one made.

Limits

These are the limits the contract publishes:

Beyond these, any request may be refused with a 429 when a key, or its organization, sends more than the API accepts: the answer always carries Retry-After, and waiting that long is all it asks.

What may change under /v1

Without a new version, the API may gain:

• a new endpoint;
• a new optional query parameter;
• a new field in an answer;
• a new value in a list of values — an error’s or a failure’s code, an upload’s status, and those of the table below.

Write your client to read a field or a value it does not know as something it does not know yet, not as an error. For some lists, the contract says how to read a value you do not know:

Never under /v1: removing or renaming anything, changing a type or a unit, or refusing a request that used to be accepted. That would be a new version, /v2.

Next steps

• Get started — a key, its permissions, and a first call.
• Read the library.
• Add a file with the API.
• Edit an asset and publish on a channel.