Skip to main content
When a request fails, Star-Pay returns a structured JSON error body alongside an HTTP error status code. All error responses share a common shape, with an error object that includes a machine-readable code and a human-readable message.

​
Error response structure

{
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v1/starpay-api/trdp/order",
  "error": {
    "code": "BadRequestException",
    "message": "Missing required payload data"
  }
}
FieldTypeDescription
statusstringAlways "error" for failed requests
timestampstringISO 8601 time the error occurred
pathstringThe request path that triggered the error
error.codestringMachine-readable error code
error.messagestringHuman-readable description of the error

​
Error types

​
400 Bad request

Returned when the request is malformed or missing required fields. 
{
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v1/starpay-api/trdp/order",
  "error": {
    "code": "BadRequestException",
    "message": "Missing required payload data, pk and payload is required"
  }
}
Common causes:
  • A required field is missing from the request body (amount, description, currency, customerName, customerPhoneNumber, items, or api_secret)
  • A field value has the wrong type or format (e.g. a non-numeric amount)
  • The items array is empty

​
401 Unauthorized

Returned when the x-api-secret header is missing, incorrect, or has been revoked. 
{
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v1/starpay-api/trdp/order",
  "error": {
    "code": "GEN_004",
    "message": "An unexpected server error occurred."
  }
}
Common causes:
  • The x-api-secret header was not included in the request
  • The secret key is incorrect or belongs to a different environment (e.g. production key used against the QA server)
  • The secret key has been rotated and the old value is no longer valid

​
404 Not found

Returned when the requested resource does not exist — for example, verifying an orderId that was never created. 
{
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v1/starpay-api/trdp/verify",
  "error": {
    "code": "ABC_001",
    "message": "not found"
  }
}
Common causes:
  • The orderId passed to /trdp/verify does not exist
  • The order was created in a different environment (e.g. QA vs. production)

​
500 Internal server error

Returned for unexpected server-side failures. These are not caused by your request and should be retried with exponential back-off. 
{
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v1/starpay-api/trdp/order",
  "error": {
    "code": "GEN_004",
    "message": "An unexpected server error occurred."
  }
}
If you consistently receive 500 errors, contact Star-Pay support. Do not retry 500 errors more than a few times without back-off.

​
Handling errors in code

async function createOrder(payload) {
  const response = await fetch(
    "https://starpayqa.starpayethiopia.com/v1/starpay-api/trdp/order",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-secret": process.env.STARPAY_API_SECRET,
      },
      body: JSON.stringify(payload),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    const { code, message } = data.error ?? {};

    switch (response.status) {
      case 400:
        throw new Error(`Bad request [${code}]: ${message}`);
      case 401:
        throw new Error("Authentication failed. Check your x-api-secret.");
      case 404:
        throw new Error(`Resource not found [${code}]: ${message}`);
      case 500:
        throw new Error("Star-Pay server error. Retry with back-off.");
      default:
        throw new Error(`Unexpected error ${response.status}: ${message}`);
    }
  }

  return data;
}

​
Common mistakes

Every order request requires amount, description, currency, customerName, customerPhoneNumber, items, and api_secret. Omitting any of these returns a 400 BadRequestException. Validate your payload before sending.
The x-api-secret header must be present on every request. Additionally, api_secret must also be included in the request body for order creation. Using a QA secret against the production endpoint (or vice versa) will result in a 401.
Passing an orderId to /trdp/verify that was never created, belongs to a different merchant, or was created in a different environment returns a 404 ABC_001 error. Ensure you are storing and using the order_id returned in the OrderCreationResponse.
If a customer tries to pay after the order’s expires_at time, the payment will fail. Always set a reasonable expiredAt value and inform customers of the payment deadline.
customerPhoneNumber must be in E.164 format (e.g. +251987654567). Passing a local format such as 0987654567 may result in a validation error.

​
Error code reference

HTTP statusError codeDescription
400BadRequestExceptionMalformed request or missing required field
401GEN_004Invalid or missing API secret
404ABC_001Requested resource not found
500GEN_004Unexpected server-side error

Build docs developers (and LLMs) love

Get started for freeTalk to us