Errors
The problems the Tractorbeam HTTP API answers a failed request with.
The Tractorbeam HTTP API answers a request it refuses or fails with an RFC 9457 problem: a JSON body of media type application/problem+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 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 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.