Error codes

Every error response from the Deploy API has the same shape:

{
  "status": 409,
  "message": "acme.com is already registered on Faable. A hostname can only point at one app — if you added it in another of your projects, remove it there first.",
  "error_code": "domain_taken",
  "docs": "https://faable.com/docs/deploy/errors#domain_taken",
  "statusCode": 409,
  "error": "Conflict",
  "code": "domain_taken"
}

• error_code is the field to branch on. It is stable: a code is never renamed or reused with another meaning, and each one maps to exactly one HTTP status.
• message is written for a person and may change between releases. Log it, show it if it reads well, but do not compare it.
• details is optional and structured. validation_error carries fields and issues (one { path, message } per failing field); repository_already_linked carries the app that holds the repository.
• action appears when there is a concrete next step the caller can offer — connect_github or install_github_app.
• statusCode, error and code are deprecated aliases kept for existing clients. code holds the same value as error_code. They will be removed; do not write new code against them.

The same contract, with its own catalogue, applies to Faable Auth.

With the SDK

@faable/deploy-sdk throws a FaableApiError on any non-2xx, and every generated method lists the codes it can throw in its docstring:

import { FaableApiError, FaableDeployApi } from '@faable/deploy-sdk'
 
try {
  await deploy.appLinkRepository(app_id, { repository })
} catch (e) {
  if (e instanceof FaableApiError) {
    switch (e.error_code) {
      case 'github_identity_missing':
        return redirectTo('/connect/github')
      case 'repository_already_linked':
        return `Already linked to ${e.details?.app_name}.`
      case 'github_installation_missing':
        return redirectTo(installUrl)
    }
  }
  throw e
}

ApiErrorCode is exported as a TypeScript union, so a switch over it is checked by the compiler.

Errors worth handling by name

Most codes are self-explanatory from the table below, but these four change what your integration should do:

The OpenAPI document

Every operation in /docs/json documents its error responses: one entry per status, with error_code restricted to the codes that operation can emit. Code generators pick them up from there.

All codes

Generated from the server’s catalogue (npm run dump-error-codes); the same list the OpenAPI ApiErrorCode schema enumerates.

Last updated on September 17, 2026