---
title: Errors
description: The problems the Tractorbeam HTTP API answers a failed request with.
---

{/* vale off */}

The Tractorbeam HTTP API answers a request it refuses or fails with an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem: a JSON body of media type `application/problem+json`.

```json
{
  "type": "https://tractorbeam.ai/docs/api-reference/errors#not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "No Branch has this name.",
  "code": "NOT_FOUND"
}
```

| Member | Meaning |
| --- | --- |
| `type` | The problem type: the URI of its section on this page. |
| `title` | The reason phrase of `status`. |
| `status` | The response's HTTP status code. |
| `detail` | What went wrong with this request, for a person to read. |
| `code` | A machine-readable code that classifies the problem more finely than `type`. |
| `errors` | Each definition an Apply refuses and why. Only an `INVALID_ARGUMENT` Apply refusal has it. |

Match on `type` or `code`, never on `title` or `detail`, which can change.

## Invalid argument

Status `400`, code `INVALID_ARGUMENT`.

A parameter, header, or body doesn't match the operation's schema or breaks one of its rules, such as a Resource definition an Apply refuses. `detail` says what is wrong, and an Apply refusal lists each definition in `errors`. A missing or malformed `Idempotency-Key` is this problem too; [Idempotent requests](/docs/api-reference/idempotency) has the key's rules. Fix the request before you send it again.

## Unauthenticated

Status `401`, code `UNAUTHENTICATED`.

The request has no credential Tractorbeam accepts, or its credential has expired. Sign in again or send a valid API key.

## Permission denied

Status `403`, code `PERMISSION_DENIED`.

The credential doesn't authorize the operation: it lacks a permission the operation needs, or its principal can't access the Workspace or Branch the request names. An App token also gets this problem for an operation that needs Workspace authority.

## Not found

Status `404`, code `NOT_FOUND`.

The Workspace doesn't hold what the request names, such as a Branch, Commit, Resource, export, or Action Invocation.

## Conflict

Status `409`. `code` says which conflict it is:

| `code` | When |
| --- | --- |
| `ALREADY_EXISTS` | What the request creates already exists. |
| `ABORTED` | Another change committed first, or the first request with the same `Idempotency-Key` is still running. Retry the same request. |
| `CONFLICT` | The Workspace's current state refuses the request. |

## Unprocessable content

Status `422`, code `IDEMPOTENCY_KEY_REUSED`.

An earlier request with a different payload already used the request's `Idempotency-Key`. A retry must repeat the first request exactly, and a new request needs a new key. [Idempotent requests](/docs/api-reference/idempotency) has the rules.

## Payload too large

Status `413`, code `PAYLOAD_TOO_LARGE`.

The request's body is longer than the operation accepts.

## Unsupported media type

Status `415`, code `UNSUPPORTED_MEDIA_TYPE`.

The request's body has a media type the operation doesn't accept.

## Resource exhausted

Status `429`, code `RESOURCE_EXHAUSTED`.

The request would take the Workspace past one of its limits, such as the length of one Blob or the Blob bytes it stores.

## Internal

Status `500`. `code` is `DATA_LOSS` when Tractorbeam read data that breaks its contract, and `INTERNAL` for any other failure of Tractorbeam's own.

## Unimplemented

Status `501`, code `UNIMPLEMENTED`.

The request needs something Tractorbeam doesn't support yet, such as the enforcement of a Marking a Resource requires.

## Unavailable

Status `503`, code `UNAVAILABLE`.

Tractorbeam can't complete the request right now, such as when the Workspace's data plane or a service Tractorbeam depends on doesn't answer. A later retry might succeed; a request that takes an `Idempotency-Key` should send the same key.
