---
title: "Error codes you will meet first · Builder's guide · Chappell AI"
description: "Appendix B of the GAAPcore builder's guide."
url: https://chappellai.us/guide/b-error-codes-you-will-meet-first/
---

Builder's guide · Appendix B

# Error codes you will meet first

| Code | HTTP | Meaning and what the screen should do |
| --- | --- | --- |
| `VALIDATION_ERROR` | 400/422 | One or more fields are wrong; mark each one from `details[].field` |
| `AMOUNT_INVALID` | 422 | An amount isn't a two-decimal string |
| `JOURNAL_UNBALANCED` | 422 | Debits don't equal credits; show both totals |
| `PERIOD_CLOSED` | 422 | The date falls in a closed period; suggest a date in an open one |
| `CONTROL_ACCOUNT_RESTRICTED` | 422 | That account is fed by a subledger; use the right document (bank, invoice, bill) |
| `INSUFFICIENT_FIFO_QUANTITY` | 422 | Not enough stock at that location to issue |
| `DOCUMENT_NOT_DRAFT` | 409 | The document was already posted; refresh and show its current state |
| `DOCUMENT_NUMBER_ASSIGNED` | 422 | A number series assigns this number; don't send one |
| `IDEMPOTENCY_KEY_MISSING` | 400 | A write without a key: a bug in your client |
| `IDEMPOTENCY_KEY_REUSED` | 409 | Same key, different body: a bug in your key handling |
| `IDEMPOTENCY_KEY_IN_PROGRESS` | 409 | The first attempt is still running; wait and retry with the same key |
| `OPERATION_NOT_PERMITTED` | 403 | The writer's role doesn't allow this route |
| `COMPANY_NOT_IN_SCOPE` | 403 | The writer isn't scoped to that company; an administrator widens the scope |
| `INTERNAL_ERROR` | 500 | Unexpected; safe to retry with the same idempotency key |

Codes are permanent: once published, a code is never renamed or reused. The full registry is section C3 of `docs/api-conventions.md`.