Error Handling

The BizCARE Books e-Invoicing API uses conventional HTTP status codes and a consistent error envelope.

Error Response Format

All API errors use a flat envelope:

{
  "success": false,
  "error": "Human-readable error message",
  "message": "Human-readable error message",
  "code": "MACHINE_CODE",
  "details": [ ... ]
}

HTTP Status Codes

Common error codes

The full set of codes per endpoint is in the API Reference.

Validation Errors (400)

details is an array of field errors — each { path, message } (plus optional summary, value):

curl -X POST https://api.bizcare.my/api/v1/invoices \
  -H "X-Api-Key: biz_test_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"type": "INVOICE"}'

{
  "success": false,
  "error": "Validation failed",
  "message": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": [
    { "path": "invoiceCode", "message": "Required" },
    { "path": "invoiceDateTime", "message": "Required" },
    { "path": "lineItems", "message": "Required" }
  ]
}

Quota Errors (402)

The API is metered. When your plan's submission quota is exhausted, invoice create and submit calls fail with (details is present on every such 402):

{
  "success": false,
  "error": "Usage limit reached",
  "message": "Usage limit reached",
  "code": "QUOTA_EXCEEDED",
  "details": { "currentUsage": 500, "limit": 500, "planName": "Standard" }
}

Forbidden Errors (403)

Returned when authenticated but the action isn't allowed. Deleting a submitted invoice:

{
  "success": false,
  "error": "A submitted invoice cannot be deleted",
  "message": "A submitted invoice cannot be deleted",
  "code": "DELETE_FORBIDDEN"
}

Missing LHDN credentials for the key's environment returns code: MISSING_CREDENTIALS.

Not Found Errors (404)

{
  "success": false,
  "error": "Company not found",
  "message": "Company not found",
  "code": "NOT_FOUND"
}

"Company not found" usually means no company is registered for your account in this key's environment. Complete company setup in the dashboard before other calls.

The status is not the same on every route. Always branch on code: NOT_FOUND, not on the HTTP status. POST /invoices, POST /submitted-documents/sync-status and POST /validation/invoice-code return 400. Most other routes return 404. GET /companies is the exception: it returns 200 with data: null.

Conflict Errors (409)

Creating an invoice whose code is already taken returns CODE_EXISTS, naming the invoice that holds it:

{
  "success": false,
  "error": "Invoice code already exists for this company",
  "message": "Invoice code already exists for this company",
  "code": "CODE_EXISTS",
  "details": { "invoiceId": "f7e6d5c4-b3a2-1098-7654-321fedcba098", "environment": "test" }
}

Invoice codes are unique per company for all time (no year component) and across both environments. A test invoice with code 1001 blocks code 1001 in live. Check details.environment to see which one holds the code. Send an Idempotency-Key on every create: a retry with the same key returns the original invoice (200, idempotentReplay: true) instead of a 409, so a 409 always means a different document holds the code. Other duplicates (adjustment-note code, company name) return code: CONFLICT. Check availability first with POST /api/v1/validation/invoice-code or /validation/adjustment-note-code.

Cancel Errors

A cancel request must send a non-empty reason in the body ({ "reason": "Wrong buyer" }). Without it you get 400 VALIDATION_ERROR.

Cancelling is allowed only within 72 hours of submission. Past that window the request is refused with 403, code: "CANCEL_FAILED" and details: { "reason": "CANCEL_WINDOW_EXPIRED" } (branch on details.reason; the message text may change). Issue a credit note instead.

Other refusals are also 403 CANCEL_FAILED, without details.reason: the document was never submitted, it is already cancelled or invalid, or the invoice still has active adjustment notes.

Submission Errors

Submitting to LHDN can also fail with:

• Not ready — code: NOT_READY (missing required buyer/supplier/line-item data).
• Wrong type — INVALID_TYPE: a PENDING_FINALIZE_* invoice can't be submitted directly.
• Transient LHDN failure — SUBMISSION_FAILED (502); retry after a brief delay.

Best Practices

• Branch on code, not on message text — messages may change; codes are stable.
• Check isCompanyReady before invoice operations — many errors stem from incomplete setup.
• Validate codes before creating documents to avoid 409.
• Parse details[].path on validation errors to give users specific feedback.
• Retry 500/502 with exponential backoff; do not retry 401/403/402 — they need manual action.