API errors

Errors

Every failed request returns the same envelope: an HTTP status and a JSON body with a machine-readable code. Branch on error.code, never on error.message — codes are stable, messages are not.

The code does not repeat the HTTP status. 404 Not Found arrives with code 400404; a request without the Authorization header arrives with HTTP 400 and code 100101. Read the status and the code independently.

{
  "error": {
    "code": 400301,
    "message": "invalid uuid format",
    "detail": "see https://en.wikipedia.org/wiki/Universally_unique_identifier"
  }
}

The API returns that link itself. It covers only one of the accepted notations: paths also take a UUID without dashes and a base58 form 21–22 characters long, so a value rejected with this code is not necessarily a malformed UUID.

Validation errors carry invalid_params, one entry per rejected field:

{
  "error": {
    "code": 400400,
    "message": "request parameters didn't validate",
    "invalid_params": [
      { "index": 0, "name": "privacy_type", "reason": "oneof", "message": "anywhere nowhere custom" }
    ]
  }
}

The same code arrives without invalid_params when a required query parameter is missing — the parameter name is then inside message:

{ "error": { "code": 400400, "message": "Parameter 'from' not found" } }

Server errors use a different shape: path and timestamp instead of detail.

{
  "error": {
    "code": 500500,
    "path": "/v1/videos",
    "message": "no message available",
    "timestamp": "2026-09-24T09:25:48.540408556Z"
  }
}

An empty request body is reported separately, with code 1 and message io error.

Fields:

X-Request-ID. Successful responses and errors 400, 401 and 500 carry this response header — quote it when contacting support. It is not sent on 404 and 405.

Numeric codes returned in error.code. A dash in the Name column means the code has no machine-readable name assigned yet — branch on the number. The Retry column says whether repeating the identical request can help.

Handling errors

• Retries. 5xx responses and network timeouts are safe to retry with exponential backoff; cap the attempts at five. Other 4xx responses should not be retried — fix the request first.
• Rate limits. The API sends neither RateLimit-* nor Retry-After. The developer guide states 10 requests per second and 300 per minute, but 50 parallel requests passed without a 429, so treat the published figure as unconfirmed and pause at least 5 seconds before repeating after one.
• Validation. Parse error.invalid_params — name is the field to fix and message lists the accepted values. When invalid_params is absent, the parameter name is inside message.
• Identifiers. 400301 and 400302 mean the identifier could not be parsed, not that the object is missing. A missing object is 400404.
• Repeating a POST. Idempotency-Key is not supported in any documented form. Assume that repeating a POST after a timeout creates a second object; check with a list request before retrying.
• Logging. Log error.code and X-Request-ID, not error.message: codes are stable, messages are not.

Codes and shapes on this page were verified against the production API on 2026-09-24. Rows marked as not reproduced are carried over from the previous catalog or from response examples and still need confirmation.