API Troubleshooting Guide

Troubleshooting assets

When submitting an asset, the API may return a 400 Bad Request response if the asset cannot be used. If you’re using SDKs, a BadRequestError will be thrown in Node or raised in Python.

The message in the error response body will include two pieces of pertinent information: the field that the error occurred for (e.g., promptImage) and the reason for the failure.

Common failures

You’re receiving a `401 Unauthorized` response

If you’re using our SDKs, you may not have set your API key. Check that you’re providing your key with the RUNWAYML_API_SECRET environment variable, or as an argument to the RunwayML SDK client constructor.

Next, be sure your API key is well-formed. Keys start with key_ and are followed by 128 hexidecimal characters (/^key_[0-9a-f]{128}$/ as a regular expression). Be sure there is no whitespace at the end of your key.

If you’re not using our SDKs:

First, check that you’re using the correct hostname. You should be using api.dev.runwayml.com for your request, not api.runwayml.com.
Be sure you’re passing the key in the Authorization header. It should look like Authorization: Bearer key_0123456789abcdef.

Other reasons why an API key might be rejected with a 401 response:

The key has been disabled in the developer portal
The account associated with the key was suspended

You’re receiving a `400 Bad Request` response

This means that the input you provided is not correct.

First, you’ll want to inspect the output of the response. You can see this output in the developer portal by clicking “Manage” at the top, then “Request History”. Select the failing request to see the response. 400 Bad Request error responses are usually formatted with a description of each error.

Here’s a breakdown of a sample error:

{
  "error": "Validation of body failed",
  "docUrl": "https://docs.dev.runwayml.com/api",
  "issues": [
    {
      "code": "custom",
      "path": ["promptImage"],
      "message": "Assets must use an approved Content-Type response header. We received \"application/octet-stream\", which is not allowed."
    }
  ]
}

The issues array contains a list of each problem encountered while inspecting your request.
The error code shows the type of problem. In this example, the error is a custom error, not a problem with the structure of the input.
The error path tells you the location of the error. A path of ["promptImage"] tells you that the problem is with the promptImage parameter. If the path was ["contentModeration","publicFigureThreshold"], it would indicate that the problem is with the publicFigureThreshold field nested inside contentModeration.
The error message tells you what is wrong. In this case, Runway attempted to fetch the image URL in promptImage with a HTTP request, but the server returned a Content-Type response header that’s not supported.

Common error reasons

Invalid data URI.: The provided data URI is malformed and could not be parsed. Be sure you’re using a library to encode the URI.
Unsupported asset type. Data URIs must include the content type of the value they encode.: Your data URI specifies a media type that’s not supported. See the list of supported media types.
Invalid URL: You provided a URL that is non-standard and cannot be parsed.
Only HTTPS URLs are allowed.: All URLs must start with https://. You cannot use http:// or other schemes, like ftp://.
URLs must be hosted on a domain.: You cannot provide a URL that points to an IP address. For instance, https://11.22.33.44/foo/bar would be rejected. You can instead create an A or AAAA record for your domain that points at the IP address of your host (in the example here, an A record pointing to 11.22.33.44). Be sure to set up HTTPS on the host for that record.
Failed to fetch asset. The URL may be incorrect or the server hosting the asset may be down.: When we attempted to fetch the asset, we encountered a non-HTTP connection issue. This might be a DNS issue, TCP connection issue, TLS problem, protocol error, or an unexpectedly closed connection. Check that the URL is working and that connections are not being rejected.
Failed to fetch asset. Received HTTP response code ”…”: When we attempted to fetch the asset, we did not get a 200 status code. The resposne code that we received is provided in the reason. Be aware that we do not follow redirects (via the Location HTTP response header).
Timeout while fetching asset.: It took longer than ten seconds to download the provided asset.
Assets must use an approved Content-Type response header. We received application/octet-stream, which is not allowed.: Your server returned application/octet-stream for the Content-Type HTTP response header. This is not allowed. See the list of supported media types.
Unsupported Content-Type response header: ”…”.: Your server returned an unsupported value for the Content-Type HTTP response header, which is noted in the response. See the list of supported media types.
Content-Length not provided: Your server did not specify a Content-Length HTTP response header. Lengths must be provided; we do not support streaming responses of unknown length.
Asset size exceeds XX.XMB.: Your server specified a Content-Length HTTP response header that exceeds the maximum size for the asset type. This error may also be returned if the number of bytes returned by the server does not match the number specified in the Content-Length response header. The maximum size is specified in the reason and in the inputs documentation.
Asset size exceeds XX.XMB.: Your server specified a Content-Length HTTP response header that exceeds the maximum size for the asset type. The maximum size is specified in the reason.
Invalid asset dimensions. Height and width must not exceed 8000px. Got XXxYY.: The provided asset is larger than 8000px on one of its sides. Assets must be less than 8000px on either side.
Invalid asset aspect ratio. width / height ratio must be between XX and YY. Got ZZ.: The aspect ratio (the asset width divided by the asset height) must be between the values XX and YY. The computed aspect ratio is included in the reason as ZZ.

Debugging failures

You can investigate the cause(s) for many common failures by simulating our request for your asset. To do this, we’ll run a cURL command against the URL you’ll specify for your asset. For this example, we’ll use the asset URL https://example.com/assets/image.jpg.

curl "https://example.com/assets/image.jpg" \
   -I \
   -H "User-Agent: RunwayML API/1.0"

You’ll receive output that looks like this:

% curl "https://example.com/assets/image.jpg" \
   -I \
   -H "User-Agent: RunwayML API/1.0"
HTTP/2 200
content-type: image/jpg
content-length: 123456
vary: Accept-Encoding
cache-control: max-age=14400
accept-ranges: bytes
alt-svc: h3=":443"; ma=86400

Your server should be returning a 200 status code.
Be sure you’re returning an acceptable Content-Type.
A Content-Length should be provided with an accurate file size.