Errors

The API answers with real HTTP status codes, so res.ok and ordinary error handling work. Every failure has the same body:

{
  "error": {
    "type": "invalid_request_error",
    "code": "VALIDATION_FAILED",
    "message": "The customer failed validation.",
    "field_errors": {
      "email": ["EMAIL_REQUIRED_FOR_EMAIL_SEND"],
      "vat_zone_ref": ["VAT_ZONE_REQUIRED"]
    },
    "request_id": "req_…"
  }
}

Branch on code, never on message. Codes are added and never renamed. An unknown code should fall through to a generic handler. A success is the bare resource, with an object field that names its kind, and has no envelope around it.

Status codes

Every code

The key and the request

Customers, products and people

Invoices

Credit notes

Recurring series and occurrences

Work registrations

The accounting system, and Tabba's own side

No code names an accounting system: see Accounting platforms.

Field errors

field_errors holds, per field of the request, the codes of what to fix. A field is named by its dotted path as the request spells it, such as lines.0.agreed_value, and _ stands for the value as a whole. Where a rule has a code of its own the entry is that code, such as VAT_ZONE_REQUIRED. Otherwise it is a sentence that says what the field should have been.

A customer, a product or a person that a body names and the company does not hold is reported here, as CUSTOMER_NOT_FOUND, PRODUCT_NOT_FOUND or ASSIGNEE_NOT_FOUND under the field.

Refusals by the accounting system

A refusal is data, not an outage. Where the accounting system said no, the error carries what it said:

{
  "error": {
    "type": "invalid_request_error",
    "code": "ISSUE_REFUSED",
    "message": "The platform refused the invoice. Nothing was booked.",
    "refusal": {
      "reason": "…",
      "params": {},
      "platform_reason": "…"
    },
    "request_id": "req_…"
  }
}

reason is a code of Tabba's own, params are its parameters, and platform_reason is the accounting system's own words, or null where it gave none. Show platform_reason to a person as the accounting system's words. An outage is PLATFORM_API_ERROR, never a refusal.

What to retry

Issuing an invoice and creating a credit note are safe to send again whatever the first answer was: an issued invoice and a booked credit note are answered as they stand.

request_id

Every response carries the id of its request in the X-Request-Id header, and every error repeats it in the body as request_id. It is req_ and a random string. Log it beside your own trace id, and quote it when you ask about a call. Every call under a key is in the account's activity log under the same id.

Rate limits

Limits are counted per key, in a sliding window of 60 seconds.

Every metered response carries three headers. They state the bucket with the least room left:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1782892860

X-RateLimit-Reset is when the window has room again, in seconds since the epoch. Past a limit the answer is 429 with RATE_LIMITED, and one header more:

Retry-After: 12

The separate platform_write bucket means that a retry loop on an issue spends its own budget and leaves your reads alone. A request refused for its scope spends nothing.

A request that carries no key, or a key that is unknown or revoked, is counted by the address it came from. Past that limit it is answered 429 in place of the 401. A request under your live key is not counted there, whatever else the same address sends.

Versioning

Changes within /api/v1 are additive. Within it, Tabba may:

• Add endpoints.
• Add optional fields to a request body.
• Add fields to a response body.
• Add event types to webhooks.
• Add error codes.

Within /api/v1, an endpoint, a field and an error code are not renamed, and a code is not moved to another status. Write your client so that an unknown field is ignored and an unknown code reaches a generic handler.