Skip to main content

HTTP Status Codes Reference

What each status actually means on this API — with the codes you might expect but will not meet. The companion guide is error handling; when a 200 carries wrong data, start at troubleshooting.

200 OK — but Check the Body​

200 means the request was understood, not that everything worked:

  • query.v1 returns its array-of-arrays envelope — an empty inner array is a successful query with no matches, which is also what a too-strict filter or a silently-repaired search produces.
  • api/asset returns 200 even when commands failed — the failures are itemised in commandFailures. Check commandFailures.count on every response. See errors and partial failures.
  • rest-1.v1 creates, updates and operations all answer 200 with the asset (including the new moment OID). So do webhook creations.

400 Bad Request​

A violation or a bad value, usually named in the body:

  • Violation tags — Violation'AssetCannotDeleteClosed, Violation'ClosedAssetCannotEditExistingValues, Violation'PrimaryWorkitemCannotHaveInvalidStatus — many are resolvable to readable text
  • Type errors — Wrong OID AssetType: Epic:3889 when a relation's value has the wrong type
  • Strict endpoints — api/webhook rejects unknown keys with a 400 and a message

Query Parameter Errors​

A malformed value in a rest-1.v1 query parameter returns 400 with a Message naming the parameter, and a nested Exception carrying the detail (such as Unknown AttributeDefinition: Story.Bogus):

  • Invalid SEL parameter
  • Invalid WHERE parameter
  • Invalid WITH parameter
  • Invalid FIND or FINDIN parameter
  • Invalid SORT parameter
  • Invalid PAGE parameter

401 Unauthorized​

Three distinct causes, one code: missing/invalid credentials, an Agility-issued token that was revoked, or access tokens disabled instance-wide. The response carries a WWW-Authenticate challenge. See authentication errors.

403 Forbidden​

Authenticated, but the member's role lacks the right for that asset or scope — see roles and permissions.

404 Not Found​

No such route, or no such asset at a rest-1 URL. (A query for a nonexistent asset is not a 404 — it is a 200 with an empty result set.)

405 Method Not Allowed​

The wrong HTTP method for the route. The famous case: api/customFields is a POST, and a GET gets a 405.

500 Internal Server Error​

On api/asset, a 500 almost always means your body never parsed — malformed JSON/YAML, or well-formed input in an impossible shape (the sibling-alias trap). The response is opaque:

{ "Exceptions": ["Server Error", "Reference: 76894036-5f86-49fd-bb4f-58970c644e2c"] }

Keep the reference GUID — it is the only handle support has. Full treatment: errors and partial failures.

Codes You Might Expect but Will Not Meet​

ExpectedReality
201Creates return 200 with the asset — on rest-1, api/asset and api/webhook
204Deletes are operations (?op=Delete) returning 200 with the asset
429Returned when a request exceeds a configured quota policy: always a possibility on Digital.ai-hosted instances, and on-premises only where an administrator has enabled rate limiting. The body identifies which limit was exceeded and how long to wait before retrying; a V1-Limit-Reason header echoes the reason. Honor RetryAfter and back off