Concepts
Errors
One error shape for every endpoint, the codes it uses, and the CLI's exit codes.
Every failure answers with the same JSON:
{
"error": {
"code": "invalid_request",
"message": "text: Required.",
"details": [{ "path": "text", "message": "Required." }]
}
}Branch on code; message is written for people and safe to show as is. details lists each problem in a request that isn't valid.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A field is missing, mistyped or unknown. Unknown fields are refused, and the message lists the ones the endpoint takes. |
| 400 | workspace_required | A personal key or OAuth token in several workspaces didn't say which. See choosing the workspace. |
| 401 | unauthorized | No key, or it's invalid, expired or turned off. |
| 402 | payment_required | The workspace's plan doesn't include the API, or a limit or monthly allowance is used up. The message says which. |
| 403 | forbidden | The guardrails don't allow it, the workspace is suspended, or the key can't act on that workspace. |
| 404 | not_found | No such endpoint, or no such item in this workspace. |
| 405 | method_not_allowed | The path exists with other methods; the Allow header lists them. |
| 409 | conflict | The item's state doesn't allow it, for example a post that already went out. |
| 413 | payload_too_large | The JSON body is over 1 MB, or the file is too big. |
| 415 | unsupported_media_type | Send application/json (or multipart/form-data to upload media). |
| 422 | unprocessable | Understood, but refused: an unknown channel or media id, brand issues to fix first. |
| 429 | rate_limited | Too many requests. Wait for Retry-After seconds. |
| 500 | internal_error | Something went wrong on Tracee's side. Safe to retry reads. |
| 503 | unavailable | A service Tracee needs is down. Retry later. |
In the CLI
The CLI prints the message (and each detail) on stderr. With --json it also prints the error object on stdout.
| Exit code | Meaning |
|---|---|
0 | Done. |
1 | Tracee refused or failed; the message says why. |
2 | The command was mistyped (unknown command, missing argument, a flag of the wrong type). Nothing was sent. |
In the SDK
Each status has its own error class, all extending TraceeError with status, code, message and details: TraceeValidationError (the other 4xx: 400, 402, 413, 415, 422), TraceeAuthError (401), TraceePermissionError (403), TraceeNotFoundError (404), TraceeConflictError (409), TraceeRateLimitError (429, with retryAfter), TraceeServerError (5xx) and TraceeConnectionError (no answer).