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.

// 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

Field	Type	Required	Description
200	OK	No	Request succeeded.
201	Created	No	Resource created (register, create sub-account).
202	Accepted	No	Order accepted into the live fill flow (trade, subscribe). Funds escrowed immediately; settlement is asynchronous.
400	Bad Request	No	Missing or invalid parameters, a missing idempotency key, or insufficient funds. Check error.code.
401	Unauthorized	No	API key missing, invalid, or expired.
403	Forbidden	No	Action not permitted: revoked/suspended key, missing scope, KYC required, frozen sub-account, or an operation outside your tier.
404	Not Found	No	Stock symbol, sub-account, holding, or instrument not found.
409	Conflict	No	Idempotency collision — a concurrent request with the same Idempotency-Key is still in progress. Retry after it resolves.
422	Unprocessable	No	Business-rule violation such as MARKET_CLOSED, a fund not being open, or requested units exceeding holdings.
429	Too Many Requests	No	Rate limit exceeded. Check X-RateLimit-Remaining and X-RateLimit-Reset headers.
500	Internal Server Error	No	Server-side failure — retry with exponential backoff or contact support.
503	Service Unavailable	No	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.

Field	Type	Required	Description
AUTH_MISSING	401	No	No API key supplied. Send Authorization: Bearer pk_live_... or X-Api-Key.
AUTH_INVALID	401	No	Key format is wrong or the key does not exist in the registry.
AUTH_SUSPENDED	403	No	Partner account temporarily suspended. Contact support@mystocks.africa.
AUTH_REVOKED	403	No	Key permanently revoked. A new key must be issued — revocation cannot be undone.
RATE_LIMITED	429	No	Too many requests. Back off and retry after X-RateLimit-Reset.
MISSING_PARAM	400	No	A required query/body parameter is absent. Check error.param or error.params[].
MISSING_IDEMPOTENCY_KEY	400	No	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	No	Symbol fails format validation (2–20 alphanumerics, optionally dot-separated). Check error.invalid[] in a batch.
UNKNOWN_EXCHANGE	400	No	Exchange code not recognised. See the supported codes list.
INVALID_TYPE	400	No	A parameter has the wrong type.
VALIDATION_ERROR	400	No	Request body or query param failed validation. See error.message.
BATCH_LIMIT_EXCEEDED	400	No	Batch exceeds the max symbol count. Check error.max and error.received.
NOT_FOUND	404	No	Requested resource does not exist.
CONFLICT	409	No	Concurrent request conflict: idempotency collision or order state changed mid-operation.
QUOTE_REQUIRED	400	No	No quoteId supplied on a trade. Every trade needs a fresh single-use quoteId from GET /quote/{symbol}.
QUOTE_NOT_FOUND	404	No	quoteId never issued, or already expired and garbage-collected. Fetch a fresh quote.
QUOTE_SCOPE_MISMATCH	403	No	quoteId belongs to a different account context. Fetch with the same subAccountId you trade on.
STALE_QUOTE	409	No	quoteId expired (60s TTL) or already used. Fetch a fresh quote and retry.
QUOTE_ORDER_MISMATCH	409	No	quoteId does not match the submitted symbol/side/quantity/cashValue. Request a new quote.
INSUFFICIENT_FUNDS	400	No	Wallet balance too low. Top up the master wallet or deposit into the sub-account first.
KYC_REQUIRED	403	No	Sub-account KYC not verified. Assert via POST /users/{userId}/kyc then retry.
MARKET_CLOSED	422	No	The exchange is closed. Check GET /market/status and retry when the venue is open.
FORBIDDEN	403	No	Authenticated but not authorised (e.g. read-only data key on a write endpoint).
INTERNAL_ERROR	500	No	Unexpected server-side failure. Safe to retry with backoff.
MAINTENANCE	503	No	Planned maintenance window. Honour the Retry-After header. In read-only maintenance, GETs still succeed and only mutations return this.
SERVICE_UNAVAILABLE	503	No	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:

Field	Type	Required	Description
full	mode	No	Every request is refused with 503 MAINTENANCE.
read_only	mode	No	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.

// 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 (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.

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.

GET

/orders/{orderId}

Get order

Full endpoint documentation

Sandbox unsupportedgetOrder

Returns a single order by ID.

Parameters

orderIdstringpathRequired

Example: ord_abc123xyz

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

orderIdstring

Unique order ID. Use to poll status or cancel.

Example: "ord_abc123xyz"

symbolstring

Example: "SCOM.KE"

namestring

Example: "Safaricom PLC"

exchangestring

Example: "NSE"

orderTypeMARKET | LIMIT | STOP | STOP_LIMIT

Order type. MARKET orders are quote-gated; LIMIT/STOP/STOP_LIMIT rest as WORKING until triggered.

Example: "LIMIT"

limitPricenumber | null

Limit price in the stock's local currency (LIMIT / STOP_LIMIT only).

stopPricenumber | null

Stop price in the stock's local currency (STOP / STOP_LIMIT only).

cancelableboolean

Whether the order can be cancelled now (DELETE). True while PENDING or WORKING.

replaceableboolean

Whether the order can be modified now (PATCH). True only for a WORKING resting order.

typeBUY | SELL

PENDING after submission. WORKING = resting LIMIT/STOP/STOP_LIMIT order waiting for its trigger price (becomes PENDING on trigger). PARTIALLY_FILLED and FILLED are the canonical execution states. REJECTED, CANCELLED, and EXPIRED are terminal outcomes. PROCESSING is a legacy transition alias and COMPLETED is a v1 compatibility alias of FILLED; neither represents custody settlement. Settlement is tracked separately as PENDING, SETTLED, or FAILED.

quoteIdstring | null

Pre-trade quote ID consumed by this order.

quoteExpiresAtstring | null

quoteUsdPricenumber | null

clientOrderIdstring | null

Partner-supplied order reference.

omsStatusstring | null

Canonical OMS lifecycle status.

timeInForcestring | null

filledQuantitynumber

remainingQuantitynumber

averageFillPricenumber | null

executionVenuestring | null

lastExecutionReportIdstring | null

executionSlaunion

Live execution SLA clock for orders that have entered the PENDING dealing-desk queue. Null while a resting order is still WORKING.

quantityinteger

priceAtOrdernumber

Stock price in local currency at submission.

usdPriceAtOrdernumber

USD equivalent of priceAtOrder.

fxRateAtOrdernumber | null

Managed FX rate used for local-to-USD conversion at order submission.

fxSourcestring | null

fxRateAsOfstring | null

fxConversionunion

feenumber

Total fee in USD (base + partner markup).

baseFeenumber

MyStocks base broker fee (0.75% of gross).

partnerMarkupFeenumber

Your markup fee component. Zero if markupBps = 0.

totalAmountnumber

BUY: gross + fee. SELL: gross - fee.

currencystring

Example: "USD"

localCurrencystring

Example: "KES"

rejectionCodestring | null

Structured rejection code. Populated when status = REJECTED.

rejectionReasonstring | null

Free-text rejection detail provided by the MyStocks internal-book execution service. Populated when status = REJECTED.

cancelledAtstring | null

settledAtstring | null

Set when custody settlement completes; independent of the canonical FILLED execution state. Legacy completed records that pre-date this field return their immutable completion/creation timestamp as compatibility evidence.

createdAtstring

settlementStatusPENDING | SETTLED | FAILED

orderLifecyclestring | null

EXPIRED for expiry; expiry is not a rejection.

cancelReasonstring | null

Response codes

200Order detail.

404Order not found.

Request reference

Sandbox unsupported

orderId Required · path

Use the API Reference for this production-only or streaming operation.

https://mystocks.africa/api/v1/partner/orders/%7BorderId%7D

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "example": "ord_abc123xyz",
      "description": "Unique order ID. Use to poll status or cancel."
    },
    "symbol": {
      "type": "string",
      "example": "SCOM.KE"
    },
    "name": {
      "type": "string",
      "example": "Safaricom PLC"
    },
    "exchange": {
      "type": "string",
      "example": "NSE"
    },
    "orderType": {
      "type": "string",
      "enum": [
        "MARKET",
        "LIMIT",
        "STOP",
        "STOP_LIMIT"
      ],
      "description": "Order type. MARKET orders are quote-gated; LIMIT/STOP/STOP_LIMIT rest as WORKING until triggered.",
      "example": "LIMIT"
    },
    "limitPrice": {
      "type": [
        "number",
        "null"
      ],
      "description": "Limit price in the stock's local currency (LIMIT / STOP_LIMIT only)."
    },
    "stopPrice": {
      "type": [
        "number",
        "null"
      ],
      "description": "Stop price in the stock's local currency (STOP / STOP_LIMIT only)."
    },
    "cancelable": {
      "type": "boolean",
      "description": "Whether the order can be cancelled now (DELETE). True while PENDING or WORKING."
    },
    "replaceable": {
      "type": "boolean",
      "description": "Whether the order can be modified now (PATCH). True only for a WORKING resting order."
    },
    "type": {
      "type": "string",
      "enum": [
        "BUY",
        "SELL"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "PENDING",
        "WORKING",
        "PARTIALLY_FILLED",
        "PROCESSING",
        "COMPLETED",
        "FILLED",
        "REJECTED",
        "CANCELLED",
        "EXPIRED"
      ],
      "description": "PENDING after submission. WORKING = resting LIMIT/STOP/STOP_LIMIT order waiting for its trigger price (becomes PENDING on trigger). PARTIALLY_FILLED and FILLED are the canonical execution states. REJECTED, CANCELLED, and EXPIRED are terminal outcomes. PROCESSING is a legacy transition alias and COMPLETED is a v1 compatibility alias of FILLED; neither represents custody settlement. Settlement is tracked separately as PENDING, SETTLED, or FAILED."
    },
    "quoteId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pre-trade quote ID consumed by this order."
    },
    "quoteExpiresAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "quoteUsdPrice": {
      "type": [
        "number",
        "null"
      ]
    },
    "clientOrderId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Partner-supplied order reference."
    },
    "omsStatus": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "RECEIVED",
        "FILLED",
        "REJECTED",
        "CANCELLED",
        "null"
      ],
      "description": "Canonical OMS lifecycle status."
    },
    "timeInForce": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "DAY",
        "GTC",
        "GTD",
        "null"
      ]
    },
    "filledQuantity": {
      "type": "number"
    },
    "remainingQuantity": {
      "type": "number"
    },
    "averageFillPrice": {
      "type": [
        "number",
        "null"
      ]
    },
    "executionVenue": {
      "type": [
        "string",
        "null"
      ]
    },
    "lastExecutionReportId": {
      "type": [
        "string",
        "null"
      ]
    },
    "executionSla": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "model": {
              "type": "string",
              "enum": [
                "LIVE_DEALING_DESK"
              ],
              "description": "Execution path covered by this SLA."
            },
            "minMinutes": {
              "type": "integer",
              "example": 1,
              "description": "Earliest expected live execution window, in minutes."
            },
            "maxMinutes": {
              "type": "integer",
              "example": 5,
              "description": "Maximum live execution window, in minutes."
            },
            "targetMinutes": {
              "type": "integer",
              "example": 5,
              "description": "Deadline used by monitoring for breach detection."
            },
            "clockStartedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "When the order entered the live execution queue."
            },
            "targetFillBy": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "Latest expected fill or rejection timestamp."
            },
            "status": {
              "type": "string",
              "enum": [
                "WITHIN_SLA",
                "BREACHED",
                "MET",
                "CANCELLED"
              ]
            },
            "breachedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "lastCheckedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            }
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "Live execution SLA clock for orders that have entered the PENDING dealing-desk queue. Null while a resting order is still WORKING."
    },
    "quantity": {
      "type": "integer"
    },
    "priceAtOrder": {
      "type": "number",
      "description": "Stock price in local currency at submission."
    },
    "usdPriceAtOrder": {
      "type": "number",
      "description": "USD equivalent of priceAtOrder."
    },
    "fxRateAtOrder": {
      "type": [
        "number",
        "null"
      ],
      "description": "Managed FX rate used for local-to-USD conversion at order submission."
    },
    "fxSource": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "MYSTOCKS_MANAGED_FX",
        "PARTNER_PROVIDED_LEGACY",
        "null"
      ]
    },
    "fxRateAsOf": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "fxConversion": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "sourceCurrency": {
              "type": "string",
              "example": "KES"
            },
            "sourceAmount": {
              "type": "number",
              "example": 65000
            },
            "targetCurrency": {
              "type": "string",
              "example": "USD"
            },
            "targetAmount": {
              "type": "number",
              "example": 500
            },
            "rate": {
              "type": "number",
              "example": 130
            },
            "rateConvention": {
              "type": "string",
              "example": "KES per USD"
            },
            "source": {
              "type": "string",
              "enum": [
                "MYSTOCKS_MANAGED_FX",
                "PARTNER_PROVIDED_LEGACY"
              ]
            },
            "asOf": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "fee": {
      "type": "number",
      "description": "Total fee in USD (base + partner markup)."
    },
    "baseFee": {
      "type": "number",
      "description": "MyStocks base broker fee (0.75% of gross)."
    },
    "partnerMarkupFee": {
      "type": "number",
      "description": "Your markup fee component. Zero if markupBps = 0."
    },
    "totalAmount": {
      "type": "number",
      "description": "BUY: gross + fee. SELL: gross - fee."
    },
    "currency": {
      "type": "string",
      "example": "USD"
    },
    "localCurrency": {
      "type": "string",
      "example": "KES"
    },
    "rejectionCode": {
      "type": [
        "string",
        "null"
      ],
      "description": "Structured rejection code. Populated when status = REJECTED.",
      "enum": [
        "INSUFFICIENT_FUNDS",
        "KYC_REQUIRED",
        "MARKET_CLOSED",
        "COMPLIANCE_HOLD",
        "TECHNICAL_ISSUE",
        "OTHER",
        "null"
      ]
    },
    "rejectionReason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Free-text rejection detail provided by the MyStocks internal-book execution service. Populated when status = REJECTED."
    },
    "cancelledAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "settledAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Set when custody settlement completes; independent of the canonical FILLED execution state. Legacy completed records that pre-date this field return their immutable completion/creation timestamp as compatibility evidence."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "canonicalStatus": {
      "type": "string",
      "enum": [
        "PENDING",
        "WORKING",
        "PARTIALLY_FILLED",
        "FILLED",
        "REJECTED",
        "CANCELLED",
        "EXPIRED"
      ]
    },
    "settlementStatus": {
      "type": "string",
      "enum": [
        "PENDING",
        "SETTLED",
        "FAILED"
      ]
    },
    "orderLifecycle": {
      "type": [
        "string",
        "null"
      ],
      "description": "EXPIRED for expiry; expiry is not a rejection."
    },
    "cancelReason": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}

curl -X GET 'https://mystocks.africa/api/v1/partner/orders/%7BorderId%7D' \
  -H "Authorization: Bearer $MYSTOCKS_API_KEY"