Errors

Every error shares the same shape:

{
  "status": 403,
  "code": "PARTNER_CANNOT_WRITE",
  "message": "…",
  "timestamp": "2026-08-19T12:00:00Z",
  "fieldErrors": {},
  "details": {},
  "retryable": false
}

Map against code, not against message: the message is meant to be read and may improve; the code is contract.

Code	Status	What it means	What to do
UNAUTHORIZED	401	The token was not issued by Costia to a registered client	Repeat the authorization flow
ACCESS_DENIED	403	The scope the endpoint requires is missing	Ask for it, or accept that the person declined
NOT_A_PARTNER_CLIENT	403	The client has no partner identity	Register the partner
PARTNER_CANNOT_WRITE	403	The partner has no verified domain	Verify the domain
PARTNER_DISABLED	403	The partner is disabled	Nothing you can fix yourself
VALIDATION_ERROR	400	The body breaks a rule	Look at fieldErrors, which names each field
UNKNOWN_LINE_TYPE	400	A line carries a lineType outside the accepted set	Fix the line
UNKNOWN_QUANTITY_UNIT	400	Same for quantityUnit	Fix the line
RESOURCE_NOT_FOUND	404	No such invoice exists for this person	—

Two that look like failures and are not

A 403 when writing is usually a decision. The consent screen has nothing pre-ticked, so your customer may have signed in without granting you invoices:write. It is not a malfunction: it is what they chose, and they were told what it meant.

An invoice from another account is a 404, not a 403. Saying an identifier exists but belongs to someone else is already saying something about that person.