Errors
On this page
Purpose
Failed requests use one JSON envelope. This page lists the codes that apply across the API. Domain codes are documented on the matching guide and in the full reference.
Envelope
{ "success": false, "errorCode": "VALIDATION_ERROR", "message": "The provided data is invalid." }
Successful responses use { "success": true, "data": {}, "meta": {} }.
Request bodies reject unknown fields. An extra property returns 400 with errorCode VALIDATION_ERROR.
Shared codes
| Code | HTTP | Meaning |
|---|---|---|
VALIDATION_ERROR | 400 | The body or query is invalid |
API_VERSION_SUNSET | 400 | Billyou-Version names a sunset version. See Versioning. |
UNAUTHORIZED | 401 | The credential is missing or rejected |
FORBIDDEN | 403 | The credential cannot access this resource |
NOT_FOUND | 404 | The resource does not exist |
RATE_LIMIT_EXCEEDED | 429 | The request exceeded the rate limit that applies to it. See Rate limits. |
INTERNAL_ERROR | 500 | Unexpected failure |
401 uses UNAUTHORIZED. The API does not return invalid_token or insufficient_scope.
A 429 uses errorCode RATE_LIMIT_EXCEEDED. The response also sends Retry-After (seconds), retryAfterSeconds in the body, and the X-RateLimit-* headers described in Rate limits.
Codes you will meet on common writes
These are not the full set. They are the ones called out for invoices, clients, and partner provisioning:
| Code | HTTP | When |
|---|---|---|
INVALID_VAT_RATE | 400 | A line VAT rate is not allowed for a Romanian client |
INVALID_SERIAL_CONFIG | 400 | Both seriesId and customSerialNumber were sent |
MISSING_SERIAL_CONFIG | 400 | A published invoice has neither series nor custom number |
NOT_LAST_IN_SERIES | 400 | Delete was called for an invoice that is not the last in its series |
CLIENT_HAS_INVOICES | 400 | Delete was called for a client that still has invoices |
ORG_EXISTS | 409 | Partner provisioning found an organization with that tax id |
PROVISIONING_TIMEOUT | 503 | Partner provisioning timed out and may still have succeeded |
Idempotency
Operations that document it accept an Idempotency-Key header. Partner account provisioning (POST /partner/accounts) is one: repeating the same key returns the original result instead of creating a second account. After PROVISIONING_TIMEOUT, retry with that same key. The partner reference has the provisioning rules.
Responses can be correlated with X-Request-Id.