KWNDevelopersالعربيةOpen KWN

Concepts

Errors

Every refusal has the same shape. Branch on code, never on the sentence.

http
HTTP/1.1 403 Forbidden
{
  "error": "Your access to Sales does not allow that. Ask your company's owner for a higher level.",
  "code": "ROLE_TOO_LOW",
  "app": "sales"
}

error is an English sentence for a log or a person; code is stable and is what your code should read. Some codes carry more fields — fields on a body that does not validate, retryAfter on a 429, app on an access refusal.

http
HTTP/1.1 400 Bad Request
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID",
  "fields": { "lines": ["At least one line is required."] }
}
StatusCodes
400REQUEST_INVALID, RULE_REFUSED, LINES_REQUIRED, CUSTOMER_REQUIRED, PRODUCT_CODE_UNKNOWN, CURSOR_INVALID, EXTERNAL_ID_INVALID, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, SELLER_TRN_MISMATCH, CUSTOMER_AMBIGUOUS, EINVOICE_TOTAL_MISMATCH, REPORT_PERIOD_INVALID, and the apps’ own rules (NO_CREDITS, CLEARANCE_UNAVAILABLE, EINVOICE_FIELDS_MISSING, PERIOD_LOCKED, …)
401API_KEY_INVALID, MERCHANT_INACTIVE
403APP_LOCKED, APP_NOT_GRANTED, ROLE_TOO_LOW, APPROVAL_REQUIRED
404NOT_FOUND — including another company’s record
409EXTERNAL_ID_TAKEN, EXTERNAL_ID_CONFLICT, CONFLICT
422IDEMPOTENCY_KEY_REUSED
429RATE_LIMITED

What to do

  • 400: the request or a business rule. Fix it before sending it again; the same request will be refused the same way.
  • 401: the key is wrong, revoked, or the company is inactive. Stop and ask the company for a working key.
  • 403: the key may not do this. Ask the company to add the scope, or the app to the plan.
  • 409: the record exists already. Read it with ?externalId= and carry on from it.
  • 429 and 5xx: retry later with the same Idempotency-Key — after Retry-After for a 429.