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:
{ "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:
errorA message for a person.error_codeA stable code to act on.parameterThe parameter, field or path parameter to blame, on a 400, 404 or 409 that names one.privilegeOn a privilege refusal, the privilege the call asked about.at_orgOn a privilege refusal, true when it was refused at one organization rather than across the workspace.causeOn an API token's privilege refusal or on a 429, why the call was refused.required_scopeWith cause set to token_scope, a scope the call needs; when more than one is missing, the next refusal names the next.incident_idOn 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
400APP_API_ERR_BAD_PARAMETERS A parameter or body field is malformed, out of range, or not one the call takes.NoAPP_API_ERR_MISSING_PARAMETER A required parameter or body field is missing.NoAPP_API_ERR_PARAMETER_TOO_LONG A value is longer than the call allows.No401APP_API_ERR_UNAUTHORIZED No credential, or one that is not valid, expired or revoked, or whose workspace is deleted.No403APP_API_ERR_FORBIDDEN Refused for a reason no more specific code names.NoAPP_API_ERR_CREDENTIAL_NOT_ADMITTED The call does not take this kind of credential.NoAPP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeThe caller does not hold a privilege the call needs.NoAPP_API_ERR_NO_PRIVILEGE_ON_ALL_ORGANIZATIONS token_scopeno_privilegeThe caller does not hold the privilege across every organization, which the call needs.NoAPP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_scopeno_privilegeThe 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.NoAPP_API_ERR_BEYOND_OWN_AUTHORITY token_scopeThe change would give or take away access the caller does not hold.No404APP_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.No409APP_API_ERR_LAST_ADMINISTRATOR The change would leave the workspace with no administrator over every organization.NoAPP_API_ERR_INVITATION_EMAIL_TAKEN The email belongs to a member, or has a pending invitation the call may not save again.NoAPP_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.NoAPP_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.NoAPP_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.NoAPP_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 first413APP_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.No429APP_API_ERR_TOO_MANY_REQUESTS call_limitinvalid_token_attemptssend_limitToo 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-After500APP_API_ERR_TECHNICAL_ISSUE The call failed on the server. A write may have taken effect: read before retrying it.Read first502APP_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-After503APP_API_ERR_MAINTENANCE Scheduled maintenance. Wait the seconds Retry-After gives, then retry.After Retry-AfterAPP_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-AfterHow 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. 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 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.