API reference

Errors

Errors come back as JSON with a detail field. For errors the app raises, detail is a sentence. For a body that fails validation, it's a list with one entry per problem.

401 Unauthorized#

The Authorization header is missing, doesn't start with Bearer , or carries the wrong token. On the event stream, a wrong ?token= gets the same error. The response has a WWW-Authenticate: Bearer header.

{
  "detail": "missing or wrong token"
}

404 Not Found#

The trace, run, sim or sim's file in the path doesn't exist, or trace_id in a new run names no trace. detail names what's missing.

{
  "detail": "run run-000000000000 not found"
}

A path under /api/ that no route serves gets a plain Not Found, without a token check.

{
  "detail": "Not Found"
}

409 Conflict#

Only Create a run returns 409, when the trace exists but isn't ready, or is the bundled sample, which can't be simulated again. Wait for it to finish processing, or check its error if it failed.

{
  "detail": "trace demo-failed is failed, not ready"
}

413 Content Too Large#

Only Upload an output file returns 413, when the file is over 64 MiB or the sim's files would pass 256 MiB in all. The app reads the whole body before it answers, so the client gets the 413 instead of a dropped connection.

{
  "detail": "file is over the 64 MiB per-file limit"
}

422 Unprocessable Entity#

422 has two shapes. When a run asks for a config the app doesn't have, or one for another architecture, or a file upload has a name the app refuses, detail is a sentence.

{
  "detail": "unknown gpu_config 'SM99_X'"
}

{
  "detail": "SM90_H100 is sm_90 but trace demo is sm_86"
}

{
  "detail": "file name 'my file.txt' must match ^(?!\\.\\.?$)[A-Za-z0-9._-]{1,128}$"
}

When the body doesn't match its model, detail is a list. Each entry has a type, a loc path into the request, a msg, the input it rejected, and sometimes a ctx with the limit.

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": [
        "body",
        "entries",
        0,
        "count"
      ],
      "msg": "Input should be greater than or equal to 1",
      "input": 0,
      "ctx": {
        "ge": 1
      }
    }
  ]
}

Server errors#

The app doesn't return 5xx on purpose. A 5xx means something failed inside the app, such as the disk filling up. Simulators should retry 5xx and network errors with backoff, and stop on any 4xx.