# Errors

A call that fails returns an HTTP status of 400 or above and a JSON body.
Here a token without the right scope tries to create an organization:

Response (403)

```json
{
  "at_org": true,
  "cause": "token_scope",
  "error": "this credential does not have the privileges to perform this action on the organization 0a9e0000-0000-4000-8000-000000000101",
  "error_code": "APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION",
  "privilege": "organization.create",
  "required_scope": "fleet:write"
}
```

Act on the HTTP status and `error_code`.
`error` is a sentence for a person, and its wording can change.

A response that is not JSON did not come from the API itself.
A call that runs longer than 90 seconds, for example, is cut off before the API can answer.
Treat it as you would a dropped connection: no response arrived, and a write may have taken effect.

## Fields

`error` and `error_code` are always present.
Some errors add fields that say what to fix:

| Field | Meaning |
| - | - |
| `error` | A message for a person. |
| `error_code` | A stable code to act on. |
| `parameter` | The parameter, field or path parameter to blame, on a 400, 404 or 409 that names one. |
| `privilege` | On a privilege refusal, the privilege the call asked about. |
| `at_org` | On a privilege refusal, `true` when it was refused at one organization rather than across the workspace. |
| `cause` | On an API token's privilege refusal or on a 429, why the call was refused. |
| `required_scope` | With `cause` set to `token_scope`, a scope the call needs; when more than one is missing, the next refusal names the next. |
| `incident_id` | On a 500, an id to quote to support: the server's log of the failure names the same id. |

A 500 also carries `incident_id`.
Quote it when you contact support.

## Codes

| Status | Code | Meaning | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A parameter or body field is malformed, out of range, or not one the call takes. | No |
| 400 | `APP_API_ERR_MISSING_PARAMETER` | A required parameter or body field is missing. | No |
| 400 | `APP_API_ERR_PARAMETER_TOO_LONG` | A value is longer than the call allows. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | No credential, or one that is not valid, expired or revoked, or whose workspace is deleted. | No |
| 403 | `APP_API_ERR_FORBIDDEN` | Refused for a reason no more specific code names. | No |
| 403 | `APP_API_ERR_CREDENTIAL_NOT_ADMITTED` | The call does not take this kind of credential. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | The caller does not hold a privilege the call needs. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_ALL_ORGANIZATIONS` (cause `token_scope` or `no_privilege`) | The caller does not hold the privilege across every organization, which the call needs. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The caller does not hold the privilege at the organization the call names. A change to an organization, agent, ingest key or registration token that does not exist, or that you cannot see, returns this too. A deleted registration token you hold the privilege over returns 409 `APP_API_ERR_CONFLICT` instead to an update, a revoke or a read of its secret, and so does a deleted ingest key to a read or a replacement of its secret. | No |
| 403 | `APP_API_ERR_BEYOND_OWN_AUTHORITY` (cause `token_scope`) | The change would give or take away access the caller does not hold. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | No such object, or one outside the caller's reach: the response is the same. Reads, grants, groups, members and invitations answer this; a change to an organization, agent, ingest key or registration token answers 403 `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` instead. | No |
| 409 | `APP_API_ERR_LAST_ADMINISTRATOR` | The change would leave the workspace with no administrator over every organization. | No |
| 409 | `APP_API_ERR_INVITATION_EMAIL_TAKEN` | The email belongs to a member, or has a pending invitation the call may not save again. | No |
| 409 | `APP_API_ERR_ALREADY_TAKEN` | The value the call would give a field is already another record's, and the field holds each value once: a group name in its workspace, or a machine install id among the live agents of an organization. `parameter` names the field. Nothing changed; change the value, or the other record, first. | No |
| 409 | `APP_API_ERR_CANNOT_DELETE_ORG_NOT_EMPTY` | The organization still holds a live agent, ingest key or organization. Nothing changed: delete or move them first. | No |
| 409 | `APP_API_ERR_CANNOT_RESTORE_PARENT_DELETED` | The organization above what the call restores is deleted: an organization's parent, or an agent's or ingest key's organization. Nothing changed: restore that organization first. | No |
| 409 | `APP_API_ERR_CONFLICT` | The call conflicts with the current state of what it acts on: an object revoked, deleted or declined, or a change that landed while the call ran. Organization names and client ids are never unique, so creating an organization never returns 409. Nothing changed: read the object again before retrying. | Read first |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The request body is larger than 1048576 bytes (1 MiB), the most a write takes. Nothing was read or changed. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts` or `send_limit`) | Too many calls with this token, too many invitation emails, or too many tokens that are not valid from one address; `cause` says which. With `call_limit` or `send_limit`, wait the seconds `Retry-After` gives and send the call again; with `invalid_token_attempts`, waiting does not help until the tokens sent from that address are fixed. | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. A write may have taken effect: read before retrying it. | Read first |
| 502 | `APP_API_ERR_AGENT_RELEASE_UNAVAILABLE` | The agent release could not be read, or SparkLogs' signature on it did not verify. No download link or hash is returned. Wait a few minutes, then retry. | After `Retry-After` |
| 503 | `APP_API_ERR_MAINTENANCE` | Scheduled maintenance. Wait the seconds `Retry-After` gives, then retry. | After `Retry-After` |
| 503 | `APP_API_ERR_NOT_CONFIGURED` | This server lacks a setting the call needs. Wait the seconds `Retry-After` gives, then retry; tell SparkLogs support if it persists. | After `Retry-After` |

## How to handle each status

| Status | Do |
| - | - |
| 400 | Fix the request. `parameter` names what is wrong when one thing is. |
| 401 | Stop. The token is missing, unknown, expired or revoked, or its owner has left the workspace. |
| 403 | Stop, and log `error_code`, `privilege`, `cause` and `required_scope` for a person to act on. See [Scopes](https://sparklogs.com/docs/api/scopes.md#when-a-call-is-refused). A change to an organization, agent, ingest key or registration token also returns 403 when the id does not exist. |
| 404 | On a read: the object does not exist, or the token cannot see it. The API returns the same response for both. |
| 409 | Your change was not applied. `APP_API_ERR_CONFLICT` means the object's state does not allow the call: it changed while the call ran, or it is deleted, revoked or declined. Read the object again and decide whether the change still makes sense. The other codes name what to change first, such as `APP_API_ERR_ALREADY_TAKEN` for a name in use, or `APP_API_ERR_CANNOT_DELETE_ORG_NOT_EMPTY` for an organization that still has agents. The same call is refused until you do. |
| 413 | The request body is over 1 MB. Nothing was read or changed. Send less in one call. |
| 429 | Read `cause`. For `call_limit` or `send_limit`, wait the seconds in the `Retry-After` header and send the call again. For `invalid_token_attempts`, stop and fix the token: retrying does not help. |
| 500 | Send the call again after a wait, as [Retries](https://sparklogs.com/docs/api/retries.md#wait-between-attempts) describes. For a write, check first whether it took effect. |
| 503 | Scheduled maintenance. Wait the seconds in `Retry-After`, then send it again. |

A query parameter or a body field that the call does not take returns 400, and `parameter` names it.
A misspelled name returns an error.
A field inside the body is named by its path, such as `grants[1].scope.zz`.
When the `Content-Type` header is wrong, `parameter` is `Content-Type`.
A body that is not valid JSON, or is JSON but not an object, returns 400 with no `parameter`.

Dates and times you send are RFC 3339, such as `2026-11-14T09:30:00Z`, between 1970 and 2200.
Anything else returns 400 naming the parameter.

---

Source: <https://sparklogs.com/docs/api/errors>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
