Snapbooks logo Snapbooks Developer

Error Handling

The error envelope

API v2 endpoints report failures with a consistent JSON envelope and an appropriate HTTP status code:

{
  "error": {
    "code": "common.validation_error",
    "message": "Invalid request.",
    "request_id": "b3c1a7e2-4f0d-4c11-9a56-8f2f6f9d1a2b",
    "details": {
      "field": "entry_date"
    }
  }
}
Field Type Description
code string Stable, machine-readable error code (see below)
message string Human-readable description of what went wrong
request_id string Correlates the response with server logs — include it when contacting support
details object Optional structured context; omitted when empty

Branch on code, not on message — messages can change, codes are an append-only contract and are never renamed.

Error codes

Codes are namespaced domain.code strings. The common namespace covers cross-cutting failures:

Code HTTP status Description
common.validation_error 400 The request payload or parameters are invalid
common.serialization_error 400 The payload could not be processed
common.not_authorized 401 Missing or invalid authentication token
common.forbidden 403 Authenticated, but not allowed — e.g. a client_account_id outside your eligible accounts
common.not_found 404 The resource does not exist
common.method_not_allowed 405 The HTTP method is not supported on this endpoint
common.not_acceptable 406 None of the requested representations are available
common.conflict 409 The request conflicts with current state
common.database_error 500 A database error occurred
common.internal_error 500 An unexpected server error occurred
common.transient_upstream_error 503 An upstream service is temporarily unavailable — safe to retry with backoff

Domain-specific codes (e.g. banking.duplicate_iban) are documented on the relevant resource pages.

OAuth endpoint errors

The OAuth endpoints (/v2/oauth/*) follow the OAuth 2.0 specification (RFC 6749) instead of the envelope above:

{
  "error": "invalid_grant",
  "error_description": "Refresh token expired"
}

See Authentication for the OAuth error catalog.

Insufficient scope

A request that exceeds the token’s scope — for example a POST with a read-only token — fails with 403 and an RFC 6750 WWW-Authenticate header:

{
  "status": 403,
  "error": "insufficient_scope",
  "message": "The write scope is required for this request"
}

Rate limiting

Authentication endpoints are rate-limited per IP (see Rate Limits). Exceeding a limit returns 429 Too Many Requests — back off and retry later.