Errors, idempotency and paging

Format

JSON with camelCase field names.
Dates as yyyy-MM-dd, timestamps as ISO 8601 in UTC.
Amounts in kroner as decimal numbers with two decimals. currency is always NOK in v1.
VAT codes are the SAF-T standard codes. For sales: 3 = 25 %, 31 = 15 %, 33 = 12 %, 5 = exempt, 6 = outside the VAT Act, 7 = no VAT treatment, 52 = export.

Errors

Every error from /v1 has the same shape:

{ "code": "not-found", "message": "Not found." }

code is stable and safe to build logic on. message is an English explanation for developers and may change. Some errors also include details with more information. Validation errors list the fields that are wrong:

{
  "code": "validation-failed",
  "message": "The request is not valid.",
  "errors": [ { "field": "lines[0].quantity", "code": "greater-than" } ]
}

Errors any endpoint can return

Status	`code`	When
401	`unauthorized`	No token, or the token is invalid, expired or refused
403	`insufficient_scope`	The client lacks the permission the endpoint needs
404	`not-found`	Does not exist in this company and environment
409	`account-closing`	The company is being closed
409	`api-client-owner-missing`	The user who created the client no longer exists. Create a new client
413	`payload-too-large`	A POST body larger than 1 MB
429	`rate_limited`	More than 600 calls a minute from one client. `Retry-After` says when to try again
500	`server-error`	Something unexpected went wrong. Retrying with the same `Idempotency-Key` is safe

An ID from another company, or from the other environment, always returns 404, never 403. The API does not reveal that something exists elsewhere.

Idempotency

Every POST requires the Idempotency-Key header. Use a new UUID for each action. If the network fails and you don’t know whether a call went through, send the same call again with the same key. Nothing happens twice.

curl https://api.envoi.no/v1/invoices/$INVOICE_ID/send \
  -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 6f1c2d0e-7b1a-4c55-9e0f-2a8d4b3c9e71"

Situation	Answer
No header	`400 idempotency-key-required`
Key longer than 255 characters	`400 idempotency-key-too-long`
First use of the key	The call runs, and its answer is stored
Same key, same call	The stored answer again, with the header `Idempotency-Replayed: true`
Same key, different body or path	`422 idempotency-key-reused`
Same key while the first call is still running	`409 idempotency-key-in-progress`, with `Retry-After: 1`
The first call ended in a 5xx error	Nothing is stored, and you can retry with the same key

Keys belong to one client in one environment and are kept for 7 days. After that, the same key counts as a new call. The exception is payments: a payment with the same key is never recorded twice, however old the key is.

Answers in the 4xx range are stored too. If you get 409 company-not-verified when sending an invoice, for example, use a new key when you retry after the company has been verified.

Paging

Lists are split into pages. Use page (from 1) and pageSize (1 to 100, default 20, 50 for journal entries).

{ "items": [ … ], "page": 1, "pageSize": 20, "totalCount": 57, "hasMore": true }

Keep going until hasMore is false. If new rows arrive while you page, later pages can shift by one. To keep another system in sync, use updatedSince on invoices instead and fetch what has changed since last time.

Get started

Authentication

Invoices

Customers

Accounting

Errors, idempotency and paging

Format

Errors

Errors any endpoint can return

Idempotency

Paging

​Format

​Errors

​Errors any endpoint can return

​Idempotency

​Paging

Format

Errors

Errors any endpoint can return

Idempotency

Paging