Request

The caller’s request was wrong: unreadable, incomplete, or a value that breaks a rule. 400 or 422.

Pattern

request.*

Raised with

fail()

Intents

Statuses

400422

View as Markdown

Intents

request.malformed400

The request cannot be read: invalid JSON, the wrong content type

request.missing400

A required field or parameter is absent

request.invalid422

A field breaks a rule: too long, the wrong format, out of range

Raising one

Name what went wrong. The intent sets the status, the message the caller sees, and any log it writes.

// The request cannot be read: invalid JSON, the wrong content type
return fail('request.malformed', 'Invalid JSON.');

// A required field or parameter is absent
return fail('request.missing', 'Handle is required.');

// A field breaks a rule: too long, the wrong format, out of range
return fail('request.invalid', 'Use 1–32 lowercase letters, numbers, or hyphens.');

The caller gets (request.malformed)

Terminal

HTTP 400

{
  "ok": false,
  "error": "Invalid JSON.",
  "code": "request.malformed"
}

Is it a request error?

Find the row that describes your case, and use the domain on the right.

If the problem is
Use
The caller’s request was wrong: unreadable, incomplete, or a value that breaks a rule. 400 or 422.
request.* this page
No valid credentials: nobody signed in, an expired session, a bad token or secret. 401.
auth.*
Valid credentials, but not allowed to do this. 403.
permission.*
The thing asked for is not there, as far as the caller may know. 404.
record.*
The request clashes with the current state: it already exists, or it is not possible yet. 409.
conflict.*
Too many requests, or an allowance used up. 429.
limit.*
Our fault or a dependency’s. The caller sees a generic message; the details are logged. 5xx.
failure.*

For registry authors

Starter intents. These are the intents prongs add errors puts in your registry, raised with fail(). Change the messages to suit your app, and the statuses through the status.* intents they are built from.