Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests.

HTTP Status Codes

Status Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request body or parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Operation not allowed (e.g., cancelling after 72 hours)
`404`	Not Found	Resource does not exist
`409`	Conflict	Duplicate resource (e.g., invoice code already exists)
`422`	Unprocessable Entity	Validation errors in request data
`500`	Internal Server Error	Server-side error

Error Response Format

Standard Error

{
  "success": false,
  "message": "Description of the error"
}

Validation Error (422)

{
  "message": "Validation failure",
  "error": {
    "status": 422,
    "code": "E_VALIDATION_ERROR",
    "messages": [
      {
        "message": "When invoice type is INVOICE, buyer is required",
        "rule": "conditional required",
        "field": "buyer"
      }
    ]
  }
}

Common Errors

Invoice Operations

Error	Status	Message
Duplicate invoice code	`409`	`"Invoice code already exists for current year"`
Not submitted yet	`403`	`"The invoice has not been submitted."`
Awaiting validation	`403`	`"The invoice has been submitted but not yet being validated by LHDN or latest submission result status is not valid."`
No submitted document	`403`	`"The invoice does not have any submitted document."`
Already cancelled	`403`	`"The latest submitted document of the invoice has already been cancelled/invalid."`
72-hour limit	`403`	`"The latest submitted document of the invoice has been submitted more than 72 hours ago. Submitted documents can only be cancelled within 72 hours."`

Retry Guidance

4xx errors: Fix the request before retrying. These indicate client-side issues.
5xx errors: Safe to retry with exponential backoff. These indicate server-side issues.
409 Conflict: Use a different invoice/adjustment note code and retry.

Error Handling

On this page