دليل المطوّرين

Errors & Lifecycle

Understanding HTTP status codes, error responses, and transaction states for proper error handling in your integration.

HTTP Status Codes

200
OK

The request was successful. Response contains the requested data.

201
Created

The resource was successfully created (e.g., new invoice submitted).

400
Bad Request

The request was invalid. Check validation errors in the response body.

401
Unauthorized

Invalid or missing API key. Ensure x-api-key header is present and valid.

404
Not Found

The requested resource doesn't exist (e.g., invoice not found).

409
Conflict

Resource already exists (e.g., duplicate invoice number).

429
Too Many Requests

Rate limit exceeded. Slow down your requests and retry after a delay.

Error Response Format

All error responses follow a consistent format with statusCode, message, and error fields:

Single Error
{
  "statusCode": 400,
  "message": "Invoice date must be today (2025-12-07). Received: 2024-12-07",
  "error": "Bad Request"
}

Validation errors may return an array of messages:

Multiple Validation Errors
{
  "statusCode": 400,
  "message": [
    "VAT must be exactly 15% of total amount",
    "Grand total must equal totalAmount + vat"
  ],
  "error": "Bad Request"
}

Transaction Status Lifecycle

Transactions move through the following statuses during their lifecycle:

PENDINGCreated, not yet validated by the system.
APPROVEDSuccessfully validated and accepted.
CASHBACK_PROCESSEDCashback has been calculated and credited to the customer.
PAIDTransaction is fully settled.
REFUNDEDTransaction was returned, and cashback was reversed.
REJECTEDValidation failed (e.g., invalid amounts, duplicates).
CANCELLEDVoided manually before processing completed.

Status Flow Diagram

PENDING→APPROVED→CASHBACK_PROCESSED→PAID
Alternative paths:REJECTED|REFUNDED|CANCELLED

Best Practices

Implementation Recommendations

  • Always use idempotency keys (UUIDs) in the x-idempotency-key header to prevent duplicate charges on network retries.
  • Pre-validate VAT (15%) and total amounts locally before submission to reduce rejection rates.
  • Ensure customers are registered in GrandShift before sending invoices; use the Lookup Customer endpoint to verify.
  • Implement exponential backoff when retrying failed requests, especially for 429 (rate limit) errors.
  • Log all API responses including error details for debugging and audit purposes.

Common Error Scenarios

Invoice Date Mismatch

Transactions must be submitted on the same day they occur.

Solution: Ensure invoiceDateis set to today's date in ISO 8601 format.

Customer Not Found

The customer phone number is not registered in GrandShift.

Solution: Use the Lookup Customer endpoint to verify the customer exists before submitting transactions.

VAT Calculation Error

VAT must be exactly 15% of the total amount.

Solution: Calculate VAT as totalAmount * 0.15 and ensure grandTotal = totalAmount + vat.

Duplicate Invoice Number

An invoice with this number already exists for your branch.

Solution: Use unique invoice numbers for each transaction. Consider using a format like BRANCH-DATE-SEQUENCE.

Insufficient Vendor Balance

Your vendor wallet doesn't have enough balance to cover the cashback.

Solution: Top up your vendor wallet balance through the dashboard or contact support.