Error Codes Reference

Complete reference for HTTP status codes, error response formats, module-specific error codes, and troubleshooting guidance.

HTTP status codes

Salami uses standard HTTP status codes. The table below lists every code you may encounter.

Standard error response format

Basic error

{
  "success": false,
  "error": "Human-readable error message"
}

Validation error (422)

{
  "success": false,
  "error": "Validation failed",
  "errors": {
    "KRAPIN": ["The KRAPIN field is required."],
    "amount": ["The amount must be greater than 0."]
  }
}

The errors object is keyed by field name. Each value is an array of validation messages for that field.

Validation error with missing fields (KRA module)

{
  "success": false,
  "error": "Missing required fields for PIN check",
  "missing_fields": ["KRAPIN"]
}

Provider error (502)

{
  "success": false,
  "error": "KRA returned an error: Invalid PIN format",
  "response_code": "E003"
}

The response_code field is only present when Salami can extract a structured error code from the upstream provider.

Payments error codes

General payment errors

M-Pesa result codes

These codes come directly from Safaricom and appear in callback payloads and status-check responses.

Airtel Money error codes

MTN Mobile Money error codes

Equity Bank error codes

SMS error codes

Send errors

SMS delivery status codes

These statuses appear in outbox queries and delivery report callbacks.

KRA Portal error codes

KRA ResponseCode values

When Salami proxies a request to the KRA developer.go.ke APIs, KRA returns a ResponseCode in its response. Salami maps failures to HTTP 502 and includes the code in response_code.

KRA validation errors

These are returned as HTTP 422 before the request reaches KRA.

eTIMS OSCU error codes

eTIMS resultCd values

KRA's eTIMS OSCU system returns a resultCd in every response. 000 means success; anything else is an error.

eTIMS validation errors (Salami-side)

These are returned as HTTP 422 before the request is forwarded to KRA.

eTIMS tax type codes

eTIMS payment type codes

General API errors

These apply across all modules.

Rate limiting

When you receive a 429, wait for the number of seconds indicated in the Retry-After header before retrying.

Troubleshooting flowchart

Request failed
  |
  +-- HTTP 401?
  |     Check Authorization header. Is the token correct, not expired, not revoked?
  |
  +-- HTTP 403?
  |     Check token scopes. Does the token have the scope required by this endpoint?
  |
  +-- HTTP 404?
  |     Does the resource (app ID, transaction ID, item code) exist and belong to you?
  |
  +-- HTTP 422?
  |     Read the `errors` object. Fix the validation issues and retry.
  |
  +-- HTTP 429?
  |     You are sending too many requests. Wait, then retry with backoff.
  |
  +-- HTTP 500?
  |     Server bug. Log the full response and contact support@dgl.co.ke.
  |
  +-- HTTP 502?
  |     Upstream provider error. Check `error` and `response_code`.
  |     Is the provider down? Retry after a delay.
  |
  +-- HTTP 503?
        Service unavailable. Check status.salami.dgl.co.ke. Retry later.

Error handling best practices

1. Always check the success field

$response = json_decode($httpResponse->getBody(), true);

if ($response['success'] === true) {
    $data = $response['data'];
    // Process successful response
} else {
    $error = $response['error'] ?? $response['message'] ?? 'Unknown error';
    Log::error('Salami API error', [
        'error' => $error,
        'response_code' => $response['response_code'] ?? null,
        'errors' => $response['errors'] ?? null,
    ]);
}

2. Implement exponential backoff for transient errors

async function callWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const status = error.response?.status;
      const isRetryable = [429, 500, 502, 503].includes(status);

      if (!isRetryable || attempt === maxRetries - 1) {
        throw error;
      }

      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

3. Map error codes to user-friendly messages

USER_MESSAGES = {
    401: "Your session has expired. Please log in again.",
    403: "You do not have permission to perform this action.",
    422: "Please check your input and try again.",
    429: "Too many requests. Please wait a moment.",
    500: "Something went wrong. Please try again later.",
    502: "The payment provider is temporarily unavailable. Please retry.",
    503: "Service is under maintenance. Please try again shortly.",
}

def get_user_message(status_code, error_detail=None):
    return USER_MESSAGES.get(status_code, "An unexpected error occurred.")

4. Log everything

For every failed API call, log:

• The HTTP method and URL
• The request body (redact sensitive fields like PINs and tokens)
• The HTTP status code
• The full response body
• A timestamp

This makes debugging with Salami support significantly faster.

Getting help

1. Check this reference -- most errors are documented above.
2. Review the endpoint documentation -- ensure your request matches the expected format.
3. Test with curl -- isolate the issue from your application code.
4. Check the status page -- https://status.salami.dgl.co.ke for outage information.
5. Contact support -- email support@dgl.co.ke with the error response, request details, and timestamps.

Back to documentation home