BillyouHelp

↑↓ select · ↵ open · Esc close

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

CodeHTTPMeaning
VALIDATION_ERROR400The body or query is invalid
API_VERSION_SUNSET400Billyou-Version names a sunset version. See Versioning.
UNAUTHORIZED401The credential is missing or rejected
FORBIDDEN403The credential cannot access this resource
NOT_FOUND404The resource does not exist
RATE_LIMIT_EXCEEDED429The request exceeded the rate limit that applies to it. See Rate limits.
INTERNAL_ERROR500Unexpected 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:

CodeHTTPWhen
INVALID_VAT_RATE400A line VAT rate is not allowed for a Romanian client
INVALID_SERIAL_CONFIG400Both seriesId and customSerialNumber were sent
MISSING_SERIAL_CONFIG400A published invoice has neither series nor custom number
NOT_LAST_IN_SERIES400Delete was called for an invoice that is not the last in its series
CLIENT_HAS_INVOICES400Delete was called for a client that still has invoices
ORG_EXISTS409Partner provisioning found an organization with that tax id
PROVISIONING_TIMEOUT503Partner 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.