Status Reference

Status specifiers (first argument)

The first argument to expectStatus declares which statuses count as success. Everything else is an error.

Form	Example	Matches
Exact code	200	Only 200
Array of codes	[200, 201]	200 or 201
Range	'2xx'	200–299
Range	'3xx'	300–399
Range	'4xx'	400–499
Range	'5xx'	500–599
Range	'1xx'	100–199
Built-in group	'success'	200–299 (same as '2xx')
Built-in group	'error'	400–599 (same as '4xx' + '5xx')
Custom group	'auth'	Instance-defined (e.g. [401, 403])
Negation	'!4xx'	Anything except 400–499
Negation	'!error'	Anything except 400–599
Negation	'!auth'	Anything except group members
Mixed array	[200, '3xx']	200 or any 300–399
Mixed array	['success', 404]	Any 2xx or 404

Dispatch keys (third argument)

Dispatch keys go in the options object. They determine how specific error statuses are handled.

Key	Example	Matches
Exact code	404	Only 404
Range	'4xx'	Any 400–499
Range	'5xx'	Any 500–599
Custom group	'auth'	Instance-defined group members

Not valid as dispatch keys: 'success', 'error', '1xx', '2xx', '3xx', negations ('!4xx').

Dispatch value types

Value type	Behaviour	Return type effect
string	Message — throws ExpectStatusError with this text	No change
(body) => T	Handler — receives typed body, can return or throw	Widens to SuccessBody | T

await expectStatus(201, response, {
  404: "Not found.", // message
  409: (body) => redirect(`/org/${body.id}`), // handler
  "5xx": "Service unavailable.", // range message
  auth: () => redirect("/sign-in"), // custom group handler
});

Dispatch key priority

When multiple keys could match, specificity wins:

Priority	Key type	Example
1 (highest)	Exact code	404
2	Range	'4xx'
3 (lowest)	Custom group	'auth'

Resolution order

Handlers (functions) are always checked before messages (strings), even across per-call and instance defaults:

Step	Source	Type
1	Per-call dispatch	Handler (function) — most specific match
2	Instance defaults	Handler (function) — most specific match
3	Per-call dispatch	Message (string) — most specific match
4	Instance defaults	Message (string) — most specific match
5	extractMessage(body)	Pulls message from response body
6	fallbackMessage	Last-resort static string
7	onError	Observability hook — fires once before throwing
8	recover	True catch-all — returns a value instead of throwing

Within each step, specificity applies: exact code → range → custom group.

Success path

When the status matches the expected status:

Step	What happens
1	onSuccess(response) fires (side-effect only)
2	transform(body) reshapes the body (if provided)
3	Return the body (or transformed body)

Built-in groups

Group	Range	Codes
'success'	'2xx'	200–299
'error'	'4xx' + '5xx'	400–599

Custom groups

Defined on the instance with groups:

const expectStatus = createExpectStatus({
  groups: {
    auth: [401, 403],
    retryable: [408, 429, 500, 502, 503, 504],
    cacheable: [200, 203, 300, 301],
  },
});

Custom groups work as:

• Status specifiers — expectStatus('auth', response)
• Dispatch keys — { auth: 'Please sign in.' }
• Negations — expectStatus('!auth', response)

Ranges

Range	HTTP class	Codes
'1xx'	Informational	100–199
'2xx'	Success	200–299
'3xx'	Redirection	300–399
'4xx'	Client Error	400–499
'5xx'	Server Error	500–599

Ranges work as both status specifiers and dispatch keys.

Where each form is valid

Form	As status specifier	As dispatch key
Exact code (200)	✅	✅
Range ('4xx')	✅	✅
'success' / 'error'	✅	❌
Custom group ('auth')	✅	✅
Negation ('!4xx')	✅	❌
Array ([200, 201])	✅	❌

See also

• Status Specifiers — detailed guide with examples
• Flat Dispatch — handler vs message priority
• Error Resolution — full resolution walkthrough
• API Overview — all exports and options