Skip to main content

Error codes

Every error answers with the same body. Branch on code; message is for people and changes with Accept-Language.

{
  "error": {
    "type": "invalid_request_error",
    "code": "phone_taken",
    "message": "Another customer already has this phone number.",
    "param": "phone",
    "docUrl": "https://docs.kosoor.com.sa/errors#phone_taken",
    "existingId": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}
FieldMeaning
typeThe family the code belongs to, one of the headings below.
codeWhat went wrong, stable across versions.
messageA sentence in the request's language.
paramThe field, query parameter or header at fault, as a path such as company.vatNumber; null when none is.
docUrlThis page, at the code's own anchor.
errorsOn a 400, every problem in the request, the first one included.
requiredPermissionOn missing_permission, the permission the call needs, such as customers:write.
existingIdOn a *_taken code, the id of the resource that already holds the value, when it is the same kind of resource and your key may read it.
missingOn customer_address_incomplete, the customer fields a standard invoice still needs, such as address.street.
zatcaErrorsOn zatca_rejected, ZATCA's own messages, each with its code, category and message.

Authentication​

missing_api_key​

HTTP status: 401

No API key was sent. Send it as Authorization: Bearer <key>.

invalid_api_key​

HTTP status: 401

The API key is not valid.

revoked_api_key​

HTTP status: 401

This API key has been revoked.

expired_api_key​

HTTP status: 401

This API key has expired.

Permissions​

tenant_suspended​

HTTP status: 403

This business's account is suspended.

missing_permission​

HTTP status: 403

This API key lacks the permission this request needs.

branch_not_allowed​

HTTP status: 403

This API key cannot act on this branch.

Invalid request​

invalid_json​

HTTP status: 400

The request body is not valid JSON.

missing_parameter​

HTTP status: 400

A required parameter is missing.

invalid_parameter​

HTTP status: 400

A parameter has an invalid value.

unknown_parameter​

HTTP status: 400

The request has a parameter this endpoint does not accept.

too_many_errors​

HTTP status: 400

The request has more problems than are listed.

unsupported_media_type​

HTTP status: 415

Send the request body as application/json.

body_too_large​

HTTP status: 413

The request body is too large.

route_not_found​

HTTP status: 404

No endpoint exists at this URL.

method_not_allowed​

HTTP status: 405

This endpoint does not accept this HTTP method.

resource_not_found​

HTTP status: 404

The resource in the URL was not found.

reference_id_taken​

HTTP status: 409

Another resource already has this referenceId.

invoice_not_cleared​

HTTP status: 409

ZATCA has not accepted this invoice. Check zatca.status.

invoice_busy​

HTTP status: 409

Another request is changing this invoice. Retry in a few seconds.

invalid_vat_number​

HTTP status: 400

A VAT number is 15 digits that start and end with 3.

vat_number_taken​

HTTP status: 409

Another customer already has this VAT number.

phone_taken​

HTTP status: 409

Another customer already has this phone number.

Business rules​

referenced_resource_not_found​

HTTP status: 422

The request names a resource that does not exist.

invoice_not_issued​

HTTP status: 422

The sales invoice was not issued.

on_account_not_allowed​

HTTP status: 422

An individual customer cannot buy on account.

credit_limit_exceeded​

HTTP status: 422

Credit limit exceeded.

customer_inactive​

HTTP status: 422

The customer is inactive.

customer_address_incomplete​

HTTP status: 422

A standard invoice needs the company customer's full address and VAT number or ID. The missing fields are listed in missing.

item_not_sellable​

HTTP status: 422

This item cannot be sold on a sales invoice.

branch_not_onboarded​

HTTP status: 422

This branch is not onboarded with ZATCA, so it cannot issue a standard invoice.

zatca_rejected​

HTTP status: 422

ZATCA rejected the invoice, so nothing was saved. ZATCA's messages are in zatcaErrors.

allocation_exceeds_due​

HTTP status: 422

The allocation is more than this invoice still owes.

invoice_not_payable​

HTTP status: 422

This invoice cannot take a payment: it does not exist, belongs to another customer or to a branch this key cannot use, is not issued, or is not a sales invoice.

period_locked​

HTTP status: 422

This date is in a closed accounting period.

payment_method_not_in_branch​

HTTP status: 422

This payment method's treasury serves another branch, so it cannot take a payment for the branch you named.

payment_not_recorded​

HTTP status: 422

The payment was not recorded.

credit_exceeds_invoice​

HTTP status: 422

This credit is more than is left to credit on the invoice.

invoice_not_creditable​

HTTP status: 422

This invoice cannot be credited: it is not an issued sales invoice, it was imported, or ZATCA rejected it.

used_subscription_not_refundable​

HTTP status: 422

This subscription has visits used, so it cannot be credited through the API.

refund_exceeds_collected​

HTTP status: 422

The refund is more than the invoice has collected.

refund_method_not_supported​

HTTP status: 422

This sale was paid by card online; a refund to the card cannot be started through the API.

loyalty_refund_blocked​

HTTP status: 422

The loyalty platform blocked this credit: points or stamps earned on this sale were already spent, the platform could not be reached, or it has not received the sale yet.

credit_note_not_issued​

HTTP status: 422

The credit note was not issued.

Idempotency​

missing_idempotency_key​

HTTP status: 400

Send an Idempotency-Key header with this request.

invalid_idempotency_key​

HTTP status: 400

The Idempotency-Key header is not valid.

idempotency_key_reused​

HTTP status: 422

This Idempotency-Key was already used with a different request.

idempotency_in_progress​

HTTP status: 409

A request with this Idempotency-Key is still being processed.

Rate limits​

rate_limited​

HTTP status: 429

Too many requests. Retry after the time in Retry-After.

Server​

internal_error​

HTTP status: 500

Something went wrong on our side. Retry, and quote the Request-Id if it keeps happening.

sandbox_unavailable​

HTTP status: 503

The sandbox is being prepared. Retry shortly.

sandbox_failed​

HTTP status: 503

The sandbox could not be built. Retrying will not help until the merchant resets it from the dashboard's Developers page.