aster.Web Data / Docs Aster UI ↗

Aster Web Data / Reference

Error codes

Every error code the service returns, with its HTTP status and the details it carries.

Codes

Every error response is an OData error object. It has a code and a message, and where they apply a target and a details array. Each detail has its own code, message and target. Clients switch on code. The message is for people, and its wording may change between releases.

Situation HTTP code Details
Success 200, 201 or 204 none none
URL, option or expression malformed or ill-typed 400 InvalidQuery target names the segment. For a $filter or $orderby that cannot be parsed, the message gives the byte position where parsing failed
Request malformed (body, header, path, or an owned child changed) 400 InvalidRequest target where known
OData-Version or OData-MaxVersion names a version the service does not speak (it speaks 4.0 and 4.01) 400 UnsupportedVersion none
Expression evaluation failed (division by zero, overflow, scalar sub-query with several rows) 400 EvaluationFailed none
Validation failed (validators, RequiredWhen, Validation.Constraint) 400 ValidationFailed One per failed rule or validator: code, target (the property path; [n]/path in a collection body), message and optional params
A server rule's check failed inside the write's group (Validation.Constraint, RequiredWhen) 400 ValidationFailed One per failed rule and row: code is the rule's identity, target is the rule's property under the member's path (Tasks[1]/Hours; none for an entity-level rule, whose message is then the top-level message when it is the only failure), and message
A write changes a field locked by ReadOnlyWhen over the stored row, or names a field hidden for the record by ViewableWhen (anything but a null over a stored null) 400 ValidationFailed code ReadOnly, target the property. The message is the lock's own, never the hiding rule's
A write changes a locked, immutable, hidden or non-writable field 400 ValidationFailed code ReadOnly, target the property
A hierarchy move would create a cycle 400 ValidationFailed code HierarchyCycle
Update or delete without a key, or a set-based write where it is not allowed 400 UpdateWithoutKey none
Cost or depth limit reached 400 QueryTooExpensive The limit hit
Authentication required or expired 401 AuthenticationRequired none
Forbidden: role, operation gate (RequiresWhen), a caller-hidden field referenced anywhere, or an action not granted 403 Forbidden none. The message is generic and does not say which part failed
Resource, key or action not found 404 NotFound none
The stored parent that a deep update inserts under was deleted before the group ran 404 NotFound none
FileSource file not found 404 FileNotFound none
Method not allowed for the resource or operation (an action called with GET, a function with POST) 405 MethodNotAllowed none
No acceptable format 406 NotAcceptable none
Duplicate key, or another database constraint conflict 409 Conflict target where known
Serialisation retries exhausted 409 TransactionConflict none
Structural action refused because the model would break 409 ModelIntegrity One per dependant that blocks it
A cascading delete sent with Prefer: aster.max-affected=N would now reach more than N rows. The preview the client confirmed is stale, and nothing is deleted 409 PreviewStale One detail, code PreviewStale, with params count (rows reached now) and max (N)
ETag stale 412 PreconditionFailed The current ETag is in the ETag header
File too large (a value over its property's maxFileSize), or file required (a saveFile of a new file or version with no contents where the set requires them) 413 or 400 FileTooLarge or FileRequired target the property
Request body in a media type the resource does not take, or a body without Content-Type. Data is JSON; a property's $value takes text/plain 415 UnsupportedMediaType target Content-Type
Member of a failed atomicity group, or dependant of a failed request 424 FailedDependency none
If-Match missing on a set with an ETag 428 PreconditionRequired none
Aster-Context over 1 KiB or 16 entries 431 RequestHeaderFieldsTooLarge none
A failure an operation or script raises on purpose: an error class, or fail (aster.fail in TypeScript) By the category it raises: 400 (ValidationFailed), 403, 404, 409, 412 or 500 The code the operation gives, else the category's code target as the operation gives it
Unsupported feature, option, collation, unpushable database-semantics expression, or a group across non-transactional backends 501 NotImplemented target the option or function
A database statement ran past statement_timeout_ms, or the request past request_deadline_ms 503 Timeout none
Lost database connection, or the database is unavailable (not reachable, or failing its start-up check). Retry-After is set: when the database is unavailable, it is the seconds to the server's next attempt 503 ConnectionLost none
Every connection of the database's pool is in use. Nothing ran. Retry-After is set 503 PoolExhausted none
An unexpected failure in the service 500 InternalError none

An over-large $top is clamped, not rejected. A 404 on a write means the record is gone, and clients remove it from their caches. A serialisation failure is never reported as 412, because clients read 412 as "reload and retry with the new ETag".

Detail codes

A detail of a ValidationFailed error. A validator's code is fixed by what it checks. A server rule's code is the rule's own identity. Each detail has a code, a target, a message and optional params, an object of the values the message uses (for example {"max": 10}). A client can use code and params to write its own message.

code Comes from params
Required A non-nullable property that is null or missing. A RequiredWhen rule uses its own identity. none
Type A value that is not of the property's type none
TooLong MaxLength, or lengthRange with a maximum max
TooShort lengthRange with a minimum min
Pattern regexp (Validation.Pattern) none
Range integerRange or floatRange (Validation.Minimum, Maximum) min, max, exclusive
NotAllowed isOneOf or valueMap (Validation.AllowedValues) none
NotUnique isUnique none
ReadOnly A write to a computed, immutable, locked (ReadOnlyWhen), hidden (ViewableWhen) or non-writable field none
HierarchyCycle A move that would make a cycle none
HierarchyHasChildren A delete of a node with children (with ModelIntegrity) none
PreviewStale A cascading delete with Prefer: aster.max-affected=N that would now reach more than N rows (with PreviewStale, 409) count, max
NotFound The stored parent a deep update inserts under was deleted before the group ran (with a 404) none
The rule's identity Validation.Constraint, RequiredWhen and gate rule IDs none