GitHub

failure.upstream

A service we depend on failed or timed out: a feed, an email provider, an API

Profile

Errors

Raised with

fail()

Status

502

Message

generic

Writes

incident.degraded
View as Markdown

Failure intents

Example

TS
return fail('failure.upstream', 'Feed host timed out.', { cause: error });
The caller gets
Terminal
HTTP 502

{
  "ok": false,
  "error": "A service we depend on isn’t responding. Try again.",
  "code": "failure.upstream"
}
And it writes incident.degraded
TS
{
  "intent": "incident.degraded",
  "level": "warn",
  "alert": false,
  "message": "Feed host timed out.",
  "data": {
    "intent": "failure.upstream",
    "cause": {
      "name": "PostgresError",
      "message": "connection terminated unexpectedly",
      "stack": "PostgresError: connection terminated…"
    }
  },
  "time": "2026-10-09T12:00:00.000Z"
}

Choosing between neighbours

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

  • If it is

    Use

  • A service we depend on failed or timed out: a feed, an email provider, an API

    failure.upstream this page

Connections

Declared in the registry, both directions. Where an intent is used in your own code is something check and the gallery see; this site has no app code.

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.

The entry prongs add errors writes into your registry. Change the message here, or the status through its status.* ref.

TS
'failure.upstream': {
  kind: 'semantic',
  description: 'A service we depend on failed or timed out: a feed, an email provider, an API',
  refs: ['status.badgateway'],
  binding: {
    publicMessage: 'A service we depend on isn’t responding. Try again.',
    logs: 'incident.degraded',
  },
},