Errors

The Agility APIs signal failure with conventional HTTP status codes and, in most cases, a body that explains what went wrong.

Status Codes

Code	Message	Meaning
400	Bad Request	The most common error. The request could not be processed. The error message identifies the specific problem, and the payload may carry Exception elements with detailed information.
401	Unauthorized	Credentials are missing, malformed, or invalid — including an expired or revoked access token.
404	Not Found	The specified resource does not exist. For asset endpoints this also covers assets the caller cannot see, since visibility is enforced before existence is disclosed.
405	Method Not Allowed	The HTTP method is not valid at this URL. Returned for any method other than GET or POST, and for a POST to a URL that does not support updating.
500	Internal Server Error	An unexpected error occurred while processing the request. The response payload contains Exception elements with information that helps diagnose the cause.

note

GET and POST only

Notice what 405 implies: these APIs are not verb-rich REST. PUT, PATCH and DELETE are generally not accepted, and destructive actions are modeled as POST to a command-shaped URL instead. Deleting a webhook subscription is the clearest example — it is a POST to .../api/webhook/delete/:id, not a DELETE.

Reading an Error Body

A 400 from the JSON endpoints returns a message describing the failure. The bulk ~/api/asset endpoint is the exception: it can return 200 OK at the HTTP layer while reporting per-command failures inside the response body, because a single request carries many independent commands. Always inspect the body of a bulk response rather than trusting the status code alone. See Bulk API (api/asset).

Query Parameter Errors

Malformed sel, where, with, find/findin, sort and page parameters produce their own distinct 400 messages, returned in the Error / Message / Exception envelope. Those literal wire strings and the envelope shape are documented once, in the "Query parameter errors" section of the HTTP status codes reference — they are not repeated here.

Violation Tags Are Localizable

Many API errors arrive as tags — Violation'AssetCannotDeleteClosed, Violation'Authentication'InvalidAccessToken — rather than prose. Some of these resolve to human-readable messages through the localization API, verbatim from a live instance:

GET ~/loc-2.v1?[Violation'AssetCannotDeleteClosed,Violation'PrimaryWorkitemCannotHaveInvalidStatus]

{
  "Violation'AssetCannotDeleteClosed": "Agility Warning: Attempting to delete a closed item.  This change was not saved.",
  "Violation'PrimaryWorkitemCannotHaveInvalidStatus": "The chosen Status is not valid for the Backlog with the assigned Team"
}

Not every error string is a resolvable tag, but a blanket "resolve every error through the localizer" strategy is safe: loc-2.v1 echoes unmatched tags back unchanged, so the worst case is the overhead of a request that returns the tag as-is — never a wrong message. Resolved messages also arrive in the caller's language, which is usually what you want to surface to a user.

Related Topics

• HTTP status codes reference — expanded treatment with handling guidance
• Query grammar reference — the syntax those parameters must satisfy
• Error handling guide — retry and recovery patterns
• HTTP headers — a wrong Content-Type is a common source of 400