Errors

Every failed request returns a JSON body with a stable, machine-readable code and a message written for humans:

{ "code": "transaction_not_found", "message": "Transaction not found." }

Branch on code. Message wording can change at any time, so don't match on it or show it to end users as-is. Treat a code you don't recognize as a generic failure of its HTTP status. While Penny is in pre-launch development, codes can change; see the compatibility policy.

Handling errors

Authentication: 401

not_authenticated means the Authorization header is missing or the token is malformed, expired, or revoked. Retrying won't help. Create a new token in Settings → API Tokens and update your integration.

Permissions: 403

• read_only_token: a read-only token made a write request. Use a read/write token.
• not_household_member: you don't belong to the household in the path, or you were removed from it. Call GET /v1/households to see the households you can access.
• insufficient_household_role: your role in the household doesn't allow the action. Viewers can only read, and some routes are limited to the owner.

A token never has more access than the person who created it, so a read/write token held by a viewer still gets insufficient_household_role on writes.

Subscription: 402

subscription_required means the household's subscription has lapsed. The body also carries the household_id it applies to:

{
  "code": "subscription_required",
  "message": "This household's subscription has lapsed",
  "household_id": "Hh4vK8pQ2sLm"
}

GET /v1/households reports these households with an access_status of subscription_required, so you can check before requesting a household's data.

Validation: 422

validation_error means the request was understood but one or more values were rejected. The errors array lists every field that failed, so you can fix them in one pass:

{
  "code": "validation_error",
  "message": "Some fields are invalid.",
  "errors": [
    {
      "field": "splits.0.amount",
      "code": "decimal_parsing",
      "message": "Input should be a valid decimal",
      "context": null
    }
  ]
}

field is the path to the value, without the request source (body, query, or path). context holds extra validator detail as a string-valued object, or null.

Not found: 404

A *_not_found code means the resource doesn't exist, was deleted, or belongs to a different household. The API doesn't say which, so it never confirms that someone else's ID exists.

Bulk transaction endpoints skip transaction IDs that are missing or ineligible and return the transactions they changed. They return a 404 only when nothing matched, so compare the returned IDs with the ones you sent to find what was skipped.

Conflicts and invalid operations: 400 and 409

These mean the request was well formed but can't be applied. A 409 conflicts with the resource's current state: a name that's already taken (duplicate_name), an export that's still being prepared (export_in_progress), or a transaction that can't be split because it's pending. A 400 is a request that can never succeed as sent, such as split amounts that don't add up to the original (sum_does_not_match_total). Change the request or the resource before retrying.

Pagination: 400

invalid_cursor means the cursor is malformed, and filters_changed means it was sent with different filters from the request that produced it. In both cases, start again without a cursor.

Uploads: 400 and 413

Images must be JPEG, PNG, or WebP (invalid_file_type) and no larger than 5 MiB (file_too_large).

Server errors: 500 and 503

internal_error means something went wrong on our side. Read requests are safe to retry. The API has no idempotency keys, so after a failed write, read the resource back before sending the request again.

service_unavailable means the request waited too long for another change to the same household, such as a bank sync, and nothing it asked for was applied. Retry it after a short wait.

Requests that don't reach an endpoint

A request body that isn't valid JSON returns 400 with the code bad_request. A path that doesn't exist returns 404 with not_found, and an HTTP method an endpoint doesn't support returns 405 with method_not_allowed, and a JSON body sent without Content-Type: application/json returns 415 with unsupported_media_type. All four use the same code and message body, with the code named after the HTTP status.

Error codes

Every code the API returns. Each endpoint's page lists the ones that apply to it.