Errors
Every failure is RFC 7807 application/problem+json, so one
shape covers all of them:
{
"title": "Bad Request",
"status": 400,
"detail": "discover: field is not queryable: password"
}
Schema validation adds a per-field list:
{
"title": "Unprocessable Entity",
"status": 422,
"detail": "validation failed",
"errors": [
{ "message": "expected number <= 1000", "location": "query.limit", "value": 2000 }
]
}
Which status means what
| Status | Meaning |
|---|---|
| 400 | The request made sense as a request but is wrong: an unqueryable field, an operator the field does not accept, a malformed ASN, a filename that is not a plain filename, a range whose start does not precede its end. Also no such object, or one outside the caller's organization, with detail Not found: the two are deliberately indistinguishable. |
| 401 | No key, or a key that no longer authenticates. |
| 403 | The key authenticated, and its group or its organization's data access does not extend to this. |
| 409 | A conflicting operation is already running. Only the IPI pipeline raises this. |
| 422 | The request failed schema validation, so it never reached a handler. |
| 500 | A genuine server-side failure. |
The distinction that matters is between 400 and 500. AIDE returned 500 for "that email already has an account", which tells the caller nothing and buries a real failure in the logs next to a routine one. Business-rule failures here are 400 with a message naming the rule.
Not found rather than 403 for another organization's data
Asking for an object belonging to another organization is the same Not found as asking for one that
does not exist. A 403 would confirm the object exists, which is itself the answer to a question the
caller is not entitled to ask.
The exception is a field an organization may not read: that is a 403 naming the field, because the caller supplied the field name and echoing it back discloses nothing they did not already know.
Unknown API paths redirect
Anything under /api that matches no route answers 302 to /api/docs rather than 404. It is a
convenience for a human with a typo, not a signal to a client.