Errors

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

Machine-readable error codes

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

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:

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