Skip to main content

Gateway Errors

When a request doesn’t reach an API, the DIS gateway tells you why. You get a structured error with a code, a short message, and a link to the matching section on this page — so you can fix the request and try again.

Use the table below to match the code from your response, then jump to the details for what to check in your application.

Error Response Structure​

All gateway errors follow a common JSON response format to help you quickly identify and resolve the issue.

Standard Error Format
{
  "error_code": "",
  "message": "",
  "error_desc": ""
}

Example Response​

Here is an example of what a missing API key error response looks like:

Example Error Response
{
  "error_code": "DIS-GE-4011",
  "message": "Missing API key",
  "error_desc": "https://developerportal.dev.digieconcenter.gov.lk/getting-started/gateway-errors#DIS-GE-4011"
}

The same error code is also returned in the DIS-GATEWAY-ERROR-CODE HTTP header, so your client can handle each case without parsing the body.

Error Codes​

Error CodeHTTP Status CodeMessageDescription
DIS-GE-4001400Missing Client IDX-DIS-CLIENT-ID header is not present in the request.
DIS-GE-4011401Missing API keyX-DIS-API-KEY header is not present in the request.
DIS-GE-4012401Incorrect api keyThe provided API key is not valid for this client.
DIS-GE-4013401Application is not activatedThe client application exists but is marked as inactive.
DIS-GE-4021402Insufficient creditsThe organization credit balance is lower than the endpoint cost.
DIS-GE-4031403Invalid Client IdThe provided client ID is not found.
DIS-GE-4032403Host is not allowedThe caller IP address is not in the application's whitelist.
DIS-GE-4033403Permission not granted for requested api and versionThe client lacks access to the API and version pair.
DIS-GE-4291429Rate limit exceededThe API rate limit has been exceeded.
DIS-GE-5020502Gateway errorThe gateway could not complete the request. Try again later.
DIS-GE-5030503Service errorThe API service is temporarily unavailable.

Error Descriptions​

DIS-GE-4001 (400) - Missing Client ID​

Reason: The request lacks the required X-DIS-CLIENT-ID header.

Solution: Ensure that your application includes the X-DIS-CLIENT-ID header in every API request.

DIS-GE-4011 (401) - Missing API key​

Reason: The request lacks the required X-DIS-API-KEY header.

Solution: Provide a valid API key using the X-DIS-API-KEY header in your request.

DIS-GE-4012 (401) - Incorrect api key​

Reason: The provided API key is not valid for this client.

Solution: Copy the current API key from your application credentials in the developer portal. If you recently rotated the key, use the new one.

DIS-GE-4013 (401) - Application is not activated​

Reason: The client application exists but is currently inactive.

Solution: Check the application status in the developer portal. If it is inactive, reactivate it or contact support.

DIS-GE-4021 (402) - Insufficient credits​

Reason: Your organization does not have enough credits for this API call.

Solution: Top up credits in the developer portal, or reduce usage until the balance is high enough.

DIS-GE-4031 (403) - Invalid Client Id​

Reason: The Client ID in X-DIS-CLIENT-ID is not recognized.

Solution: Copy the active Client ID from your application in the developer portal and send it on every request.

DIS-GE-4032 (403) - Host is not allowed​

Reason: The IP address from which the request originated is not in your application's configured IP whitelist.

Solution: Add the caller's IP address to the whitelist in the developer portal under the application's security settings.

DIS-GE-4033 (403) - Permission not granted for requested api and version​

Reason: Your client application does not have an active subscription or access rights to the specific API and version requested.

Solution: Ensure that your application is subscribed to the correct API and version in the developer portal.

DIS-GE-4291 (429) - Rate limit exceeded​

Reason: You have exceeded the permitted number of requests per minute for this API.

Solution: Wait until the next minute for the rate limit window to reset before sending more requests.

DIS-GE-5020 (502) - Gateway error​

Reason: The gateway could not complete the request due to a temporary internal issue.

Solution: Wait a moment and retry. If the error continues, contact support and include the error code from the response.

DIS-GE-5030 (503) - Service error​

Reason: The API service that handles this request is temporarily unavailable.

Solution: Try again later. If the error continues, contact support and include the error code from the response.