Skip to main content

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
{  "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:

FieldMeaning
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​

StatusCodeMeaningSend again?
400APP_API_ERR_BAD_PARAMETERSA parameter or body field is malformed, out of range, or not one the call takes.No
400APP_API_ERR_MISSING_PARAMETERA required parameter or body field is missing.No
400APP_API_ERR_PARAMETER_TOO_LONGA value is longer than the call allows.No
401APP_API_ERR_UNAUTHORIZEDNo credential, or one that is not valid, expired or revoked, or whose workspace is deleted.No
403APP_API_ERR_FORBIDDENRefused for a reason no more specific code names.No
403APP_API_ERR_CREDENTIAL_NOT_ADMITTEDThe call does not take this kind of credential.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeThe caller does not hold a privilege the call needs.No
403APP_API_ERR_NO_PRIVILEGE_ON_ALL_ORGANIZATIONStoken_scopeno_privilegeThe caller does not hold the privilege across every organization, which the call needs.No
403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONtoken_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.No
403APP_API_ERR_BEYOND_OWN_AUTHORITYtoken_scopeThe change would give or take away access the caller does not hold.No
404APP_API_ERR_RECORD_NOT_FOUNDNo 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
409APP_API_ERR_LAST_ADMINISTRATORThe change would leave the workspace with no administrator over every organization.No
409APP_API_ERR_INVITATION_EMAIL_TAKENThe email belongs to a member, or has a pending invitation the call may not save again.No
409APP_API_ERR_ALREADY_TAKENThe 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
409APP_API_ERR_CANNOT_DELETE_ORG_NOT_EMPTYThe organization still holds a live agent, ingest key or organization. Nothing changed: delete or move them first.No
409APP_API_ERR_CANNOT_RESTORE_PARENT_DELETEDThe 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
409APP_API_ERR_CONFLICTThe 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
413APP_API_ERR_BODY_TOO_LARGEThe request body is larger than 1048576 bytes (1 MiB), the most a write takes. Nothing was read or changed.No
429APP_API_ERR_TOO_MANY_REQUESTScall_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-After
500APP_API_ERR_TECHNICAL_ISSUEThe call failed on the server. A write may have taken effect: read before retrying it.Read first
502APP_API_ERR_AGENT_RELEASE_UNAVAILABLEThe 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
503APP_API_ERR_MAINTENANCEScheduled maintenance. Wait the seconds Retry-After gives, then retry.After Retry-After
503APP_API_ERR_NOT_CONFIGUREDThis 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​

StatusDo
400Fix the request. parameter names what is wrong when one thing is.
401Stop. The token is missing, unknown, expired or revoked, or its owner has left the workspace.
403Stop, 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.
404On a read: the object does not exist, or the token cannot see it. The API returns the same response for both.
409Your 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.
413The request body is over 1 MB. Nothing was read or changed. Send less in one call.
429Read 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.
500Send the call again after a wait, as Retries describes. For a write, check first whether it took effect.
503Scheduled 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.