API / Errors

API

Errors

Status codes and the error format.

Errors are returned as JSON with a message that's safe to show to a person:

json
{"error": "Mutation level must be between 0 and 3."}

The message is meant for people. To decide what to do in code, use the status code.

Status codes#

Status When
200 OK Success. Also returned instead of 201 for a duplicate upload or job submission.
201 Created A new binary, profile or job.
204 No Content A delete or cancel succeeded.
401 Unauthorized Missing, invalid or revoked API key. See Authentication.
404 Not Found The resource doesn't exist, or belongs to another organization.
409 Conflict A profile name is already taken, or the job has already finished (cancel).
410 Gone The job's output and diagnostics were deleted after the retention period.
422 Unprocessable Entity The request was understood but rejected: an invalid file, an unknown option, a value out of range, a malformed body.
500 Internal Server Error Something went wrong on our side. It's logged; retrying later is safe.

Request bodies#

JSON bodies must be a single object with only the documented fields; unknown fields are rejected with 422 so that typos don't go unnoticed. Bodies are limited to 64 KB, uploads to 50 MB.

Retrying#

Every request can be retried safely:

  • Uploading the same file again returns the existing binary.
  • Submitting the same job while an identical one is queued or running returns that job.
  • Cancelling a finished job, or deleting something already deleted, returns an error but changes nothing.