> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mioesim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MIOeSIM API error codes and troubleshooting

> Reference for the code field in every MIOeSIM API response — what each value means, how to resolve common errors, and how to debug signature and token issues.

Every MIOeSIM API response uses a consistent envelope with three top-level fields:

```json Response envelope theme={null}
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

* `code` — an integer indicating whether the request succeeded or failed. Check this field before processing `data`.
* `message` — a human-readable string accompanying the code. Useful for logging and debugging.
* `data` — the response payload. This field is `null` or absent when the request fails.

Always check `code` first. A `200 HTTP` status does not guarantee a successful operation — errors are signalled through the `code` field, not the HTTP status.

## Success codes

| Code | Endpoint                   | Meaning                                                            |
| ---- | -------------------------- | ------------------------------------------------------------------ |
| `0`  | All endpoints except login | Request succeeded. The `data` field contains the response payload. |
| `1`  | Login (`/api_order/login`) | Login succeeded. The `data` field contains your access token.      |

## Error codes

| Code     | Meaning                             | How to resolve                                                                                                                                                             |
| -------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-1`     | Token expired                       | Your access token is no longer valid. Re-authenticate via the login endpoint to obtain a new token.                                                                        |
| `-2`     | Required parameter is null or empty | One or more required fields are missing from the request body. Check the endpoint's parameter list and ensure all required fields are present and non-empty.               |
| `-3`     | Data not found / operation failed   | The requested resource does not exist, or the operation could not be completed. Verify that the identifiers you passed (order number, ICCID, etc.) are correct.            |
| `-8`     | Query failed                        | The query could not be executed. Check your filter parameters for invalid values or unsupported combinations.                                                              |
| `-10`    | `dpId` is null                      | The `dpId` field is required for this endpoint but was not provided. Include your distribution partner ID in the request.                                                  |
| `-30`    | Signature is wrong                  | The request signature did not validate. Recalculate the signature — see [Invalid signature (-30)](#invalid-signature--30) below.                                           |
| `3`      | Data does not exist                 | The referenced record was not found. Used by some endpoints as an alternative to `-3`.                                                                                     |
| `4`      | Order status abnormal               | The order is not in a valid state for the requested operation. Check the order's current `status` before retrying. See [Order status codes](/reference/order-statuses).    |
| `22`     | Non-personal order                  | The operation is not permitted on this order type. This order was not placed as a personal order.                                                                          |
| `99`     | PDF / email error                   | PDF generation failed or a file exception occurred. Retry the request. If the error persists, check that your order is in status `0` (active) and contact MIOeSIM support. |
| `400108` | Access denied                       | Your IP address is not on the whitelist for the `getESIMDetail` endpoint. Contact MIOeSIM to add your server's IP address.                                                 |
| `400109` | Access not supported                | Your account is not enabled for the `getESIMDetail` endpoint. Contact MIOeSIM to request access.                                                                           |

## Troubleshooting common issues

<AccordionGroup>
  <Accordion title="Token expired (-1)">
    Your token has a fixed expiry. When you receive `code: -1`, your current token is no longer accepted by the API.

    To recover:

    1. Call `POST /api_order/login` with your credentials to obtain a new token.
    2. Update the token stored in your application.
    3. Retry the original request with the new token.

    To avoid repeated expiry errors, track the token's issue time and proactively refresh it before it expires rather than waiting for a `-1` response. The login response includes an expiry value you can use to schedule a refresh.
  </Accordion>

  <Accordion title="Invalid signature (-30)">
    The signature you sent does not match what the MIOeSIM server calculated. Work through the following checklist to find the mismatch:

    * **Parameter sorting** — parameters must be sorted in ascending alphabetical order by key before building the signature string.
    * **Key appending** — append your secret key directly to the end of the concatenated parameter string, with no separator. The format is `param1=value1param2=value2YOUR_SECRET_KEY`.
    * **MD5 encoding** — the final signature must be the MD5 hash of the full string, expressed as a lowercase hexadecimal string.
    * **Excluded parameters** — do not include the `sign` parameter itself in the string you hash.
    * **Empty values** — exclude parameters with empty or null values from the signature string.
    * **Encoding** — ensure the string is UTF-8 encoded before hashing.

    Log the exact string you are hashing (before MD5) and compare it character by character against what the server would expect to isolate the discrepancy.
  </Accordion>

  <Accordion title="Missing parameters (-2)">
    The request is missing one or more required fields. To resolve this:

    1. Check the endpoint's parameter documentation and confirm all required fields are included in your request body.
    2. Verify that required string fields are non-empty strings — a field present but set to `""` or `null` will trigger this error.
    3. Check for typos in parameter names — the API performs exact key matching.

    The `message` field in the response may name the specific parameter that is missing or empty, which can speed up diagnosis.
  </Accordion>

  <Accordion title="Access denied (400108 / 400109)">
    These error codes apply to the `getESIMDetail` endpoint and indicate that access from your server is not permitted.

    * **400108 — IP not whitelisted**: the request was made from an IP address that has not been approved for your account. Contact MIOeSIM and provide the IP address of your server. Once added to the whitelist, requests from that address will be accepted.
    * **400109 — Access not supported**: your account does not have permission to use `getESIMDetail`. Contact MIOeSIM to request that this endpoint be enabled for your account.

    Both error codes require action on the MIOeSIM side — there is no client-side fix beyond ensuring you are calling from the correct IP.
  </Accordion>
</AccordionGroup>

<Warning>
  Never include your secret key in client-side code, mobile applications, or any environment where it could be extracted by a third party. All signed requests must be constructed server-side. If your secret key is compromised, contact MIOeSIM immediately to rotate your credentials.
</Warning>