Errors and troubleshooting

Error format

Errors use one envelope, whichever layer refused the call. Branch on error.code, never on the message: messages are written for people and may change.

{
  "ok": false,
  "error": {
    "code": "insufficient_scope",
    "message": "This API key has not been granted the permission this request needs.",
    "details": { "required_ability": "invoices:issue" }
  }
}

Language of messages

Messages are in Arabic unless the request's Accept-Language header prefers English (Accept-Language: en, en-US and so on); Arabic is used for anything else, or when the header is absent. Every answer names its language in the Content-Language header. Codes, field names and data never change with the language. The MCP server follows the opposite default for AI agents: English unless the client asks for Arabic.

Error codes

Validation errors

HTTP/1.1 422 Unprocessable Content

{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "The submitted data is invalid.",
    "details": {
      "issue_date": ["The issue date field is required."],
      "items.0.unit_price": ["The items.0.unit_price field is required."]
    }
  }
}

Troubleshooting

I get an HTML page instead of JSON

Send Accept: application/json on every request. Without it, a mistyped URL can answer with the website's HTML error page instead of a JSON error.

401 although the key looks right

• The header must be Authorization: Bearer <key> (one space, no quotes) or X-Api-Key: <key>.
• Keys in the URL are refused.
• The key may have been rotated: the old key stops working the moment it is rotated. An expired key answers token_expired instead.
• The user who created the key may have left the company. Create a new key.

403 forbidden when issuing

The key needs invoices:issue, and its creator needs the permission to issue invoices. A user with a view-only or limited role cannot issue through a key either.

Issuing fails with invoice_not_issuable

Read error.message; it names the problem. The most common causes: the company VAT number or address is incomplete; a business buyer of a standard invoice has no complete national address; a zero-rated or exempt line has no vat_exemption_code. Create a draft ("issue": false) to keep the data while you fix it.

The invoice is issued but deliverable is false

A standard invoice waits for ZATCA clearance. Read it again after a short wait. If its status becomes rejected, errors holds ZATCA's reasons.

A retry created a second invoice

Send external_reference. Without it, every call is a new invoice.

Getting help

Write to us with the time of the call, the HTTP status and error.code. Never send the API key itself.