# Errors

> Every MyStocks Partner API error carries a machine-readable error.code and a human-readable error.message. Full reference of HTTP status codes, error codes, and structured order-rejection codes.

Every error response carries a top-level `error` object with a machine-readable `code` string and a
human-readable `message`. This applies to all endpoints. Check `error.code` for programmatic handling;
use `error.message` for logging or UI display.

```jsonc
// 401 auth error
{ "error": { "code": "AUTH_MISSING", "message": "Provide a valid partner API key via Authorization: Bearer pk_live_... or X-Api-Key header." } }

// 400 validation error
{ "error": { "code": "VALIDATION_ERROR", "message": "Ambiguous symbol \"MTN\" matches multiple listings: MTN.GH, MTN.NG. Use an exchange-qualified symbol." } }
```

## HTTP status codes

200 (OK, optional): Request succeeded.

201 (Created, optional): Resource created (register, create sub-account).

202 (Accepted, optional): Order accepted into the live fill flow (trade, subscribe). Funds escrowed immediately; settlement is asynchronous.

400 (Bad Request, optional): Missing or invalid parameters, a missing idempotency key, or insufficient funds. Check error.code.

401 (Unauthorized, optional): API key missing, invalid, or expired.

403 (Forbidden, optional): Action not permitted: revoked/suspended key, missing scope, KYC required, frozen sub-account, or an operation outside your tier.

404 (Not Found, optional): Stock symbol, sub-account, holding, or instrument not found.

409 (Conflict, optional): Idempotency collision — a concurrent request with the same Idempotency-Key is still in progress. Retry after it resolves.

422 (Unprocessable, optional): Business-rule violation such as MARKET\_CLOSED, a fund not being open, or requested units exceeding holdings.

429 (Too Many Requests, optional): Rate limit exceeded. Check X-RateLimit-Remaining and X-RateLimit-Reset headers.

500 (Internal Server Error, optional): Server-side failure — retry with exponential backoff or contact support.

503 (Service Unavailable, optional): Planned maintenance (MAINTENANCE) or an unplanned dependency outage (SERVICE\_UNAVAILABLE). Always carries Retry-After. Never means your request was wrong — retry it unchanged.

## Machine-readable error codes

When the `error` field is an object, `error.code` is one of the values below.

AUTH\_MISSING (401, optional): No API key supplied. Send Authorization: Bearer pk\_live\_... or X-Api-Key.

AUTH\_INVALID (401, optional): Key format is wrong or the key does not exist in the registry.

AUTH\_SUSPENDED (403, optional): Partner account temporarily suspended. Contact support\@mystocks.africa.

AUTH\_REVOKED (403, optional): Key permanently revoked. A new key must be issued — revocation cannot be undone.

RATE\_LIMITED (429, optional): Too many requests. Back off and retry after X-RateLimit-Reset.

MISSING\_PARAM (400, optional): A required query/body parameter is absent. Check error.param or error.params\[].

MISSING\_IDEMPOTENCY\_KEY (400, optional): An authenticated POST, PATCH, PUT, or DELETE was sent without the required Idempotency-Key header. The documented registration, reset, application, upgrade, and OAuth token endpoints are exempt.

INVALID\_SYMBOL (400, optional): Symbol fails format validation (2–20 alphanumerics, optionally dot-separated). Check error.invalid\[] in a batch.

UNKNOWN\_EXCHANGE (400, optional): Exchange code not recognised. See the supported codes list.

INVALID\_TYPE (400, optional): A parameter has the wrong type.

VALIDATION\_ERROR (400, optional): Request body or query param failed validation. See error.message.

BATCH\_LIMIT\_EXCEEDED (400, optional): Batch exceeds the max symbol count. Check error.max and error.received.

NOT\_FOUND (404, optional): Requested resource does not exist.

CONFLICT (409, optional): Concurrent request conflict: idempotency collision or order state changed mid-operation.

QUOTE\_REQUIRED (400, optional): No quoteId supplied on a trade. Every trade needs a fresh single-use quoteId from GET /quote/{symbol}.

QUOTE\_NOT\_FOUND (404, optional): quoteId never issued, or already expired and garbage-collected. Fetch a fresh quote.

QUOTE\_SCOPE\_MISMATCH (403, optional): quoteId belongs to a different account context. Fetch with the same subAccountId you trade on.

STALE\_QUOTE (409, optional): quoteId expired (60s TTL) or already used. Fetch a fresh quote and retry.

QUOTE\_ORDER\_MISMATCH (409, optional): quoteId does not match the submitted symbol/side/quantity/cashValue. Request a new quote.

INSUFFICIENT\_FUNDS (400, optional): Wallet balance too low. Top up the master wallet or deposit into the sub-account first.

KYC\_REQUIRED (403, optional): Sub-account KYC not verified. Assert via POST /users/{userId}/kyc then retry.

MARKET\_CLOSED (422, optional): The exchange is closed. Check GET /market/status and retry when the venue is open.

FORBIDDEN (403, optional): Authenticated but not authorised (e.g. read-only data key on a write endpoint).

INTERNAL\_ERROR (500, optional): Unexpected server-side failure. Safe to retry with backoff.

MAINTENANCE (503, optional): Planned maintenance window. Honour the Retry-After header. In read-only maintenance, GETs still succeed and only mutations return this.

SERVICE\_UNAVAILABLE (503, optional): Unplanned outage in a downstream dependency. Retry with exponential backoff; check the status page.

## Maintenance and downtime

During a maintenance window the Partner API returns `503` with a `Retry-After` header (in seconds).
There are two modes, reported as `error.mode`:

full (mode, optional): Every request is refused with 503 MAINTENANCE.

read\_only (mode, optional): GET and HEAD are served normally; every mutation (orders, payments, account changes) is refused with 503 MAINTENANCE. Used during a settlement or payment-rail incident so you can still read positions and reconcile while money movement is frozen.

```jsonc
// 503 during a read-only window
{
  "error": {
    "code": "MAINTENANCE",
    "message": "The Partner API is in read-only maintenance: reads are being served normally, but order, payment, and account mutations are temporarily refused.",
    "mode": "read_only",
    "endsAt": "2026-07-14T02:00:00.000Z",
    "statusPage": "https://mystocks.africa/status"
  }
}
```

Do not treat a `503` as a rejected request — nothing was processed, and the same request is safe to
send again once `Retry-After` elapses. Keep your `Idempotency-Key` the same when you retry.

Live status, uptime, and incident history are published at
[mystocks.africa/status](https://mystocks.africa/status) (raw JSON: `GET /api/v1/status`). You do not
need to poll it: incidents are pushed to your webhooks as `incident.declared` / `incident.resolved`.

## Order rejection codes

The codes above are returned **synchronously** — the HTTP call itself fails and no order is created.
A `rejectionCode` is different: it is attached **asynchronously**, when an order that was already
accepted (`202`, status `PENDING`) is later rejected by the MyStocks internal-book execution engine. You learn about it through
the `order.rejected` webhook, the execution report, or `rejectionCode` on `GET /orders/{orderId}` —
always alongside the free-text `rejectionReason`.

This is the exhaustive list. No other value is ever written.

INSUFFICIENT\_FUNDS (retriable, optional): The account lacked settled balance at settlement time. Top up and resubmit.

MARKET\_CLOSED (retriable, optional): The exchange was closed when the desk attempted execution. Orders placed outside market hours are normally queued rather than rejected, so this usually indicates an unscheduled closure. Check GET /market/status, then resubmit.

TECHNICAL\_ISSUE (retriable, optional): Execution failed for an operational reason at the venue or on the desk. Safe to resubmit; if it recurs, check /status for an open incident.

KYC\_REQUIRED (not retriable, optional): The account is not KYC-approved. Complete KYC via POST /users/{userId}/kyc, wait for kyc.updated, then resubmit. Retrying as-is will be rejected again.

COMPLIANCE\_HOLD (not retriable, optional): Blocked by compliance review (sanctions, market-abuse check, restricted security, or an account hold). Do not resubmit — contact support\@mystocks.africa.

OTHER (not retriable, optional): Does not fit a category above. rejectionReason always carries the specific explanation.

`retriable` means resubmitting the same order unchanged could plausibly succeed later. `not retriable`
means something must change first — funds, KYC, the order itself — or the same rejection will repeat.

Order **expiry** is not a rejection. When a `DAY` or `GTD` order reaches its deadline it is
**cancelled**, carrying `orderLifecycle: "EXPIRED"` and a `cancelReason` — never a `rejectionCode`.
