SAHMK

Viewing: Error Codes

Error Codes

The API uses standard HTTP status codes and returns structured JSON error responses.

HTTP Error Codes

400INVALID_ROUTE

Wrong endpoint path was used. The API returns a suggested correct route.

401AUTH_REQUIRED

The X-API-Key header is missing. The body includes error.code and detail.

403INVALID_API_KEY

API key format is invalid, or the key is invalid or revoked. The body includes error.code and detail.

403PLAN_LIMIT

Endpoint requires a higher plan (e.g., historical data requires Starter+, or higher-tier financials combinations are requested on Starter).

404INVALID_SYMBOL

Exchange symbol was not found.

404 / 409INVALID_IDENTIFIER / AMBIGUOUS_IDENTIFIER

Identifier query did not resolve or matched multiple companies.

429RATE_LIMITED(edge)

Nginx edge burst or connection guard. The body is error.code and error.message.

429RATE_LIMITED(application)

App daily, per-minute, IP, or temporary security throttle. The body includes error.code and detail.

500SERVER_ERROR

Internal server error. Please retry or contact support.

Temporary security limits for new accounts

Some new free accounts may temporarily hit a security limit. If this happens, the API returns HTTP 429 with a detail containing Temporary security limit reached. Honor Retry-After when present and try again later.

Common integration error: Calling GET /api/v1/quote/batch/ returns 400 INVALID_ROUTE with route guidance.

json
{
  "error": {
    "code": "INVALID_ROUTE",
    "message": "Did you mean /api/v1/quotes/?symbols=2222,1120 ?"
  }
}

Responses for a missing API key (401), an invalid or revoked key (403), and a quota or rate limit (429) include error.code and error.message, and also retain the top-level detail field. For quota-related HTTP 429 responses, the top-level upgrade object is returned alongside error.

Error Response Formats

Endpoint validation and lookup errors generally use a structured error object:

json
{
  "error": {
    "code": "INVALID_SYMBOL",
    "message": "Stock symbol '9999' not found."
  }
}

When the Nginx request-rate limit is exceeded, HTTP 429 is returned before the application processes the request. Retry-After is 1, and the same response is used on api.sahmk.sa and app.sahmk.sa:

json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Request rate limit exceeded. Please retry shortly."
  }
}

Errors for a missing or rejected API key, the daily quota, the per-minute limit, an IP limit, and a temporary security restriction include error.code and retain the top-level detail field. For a daily-quota HTTP 429, the upgrade object is returned alongside error.

json
{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "A valid X-API-Key is required."
  },
  "detail": "A valid X-API-Key is required."
}

Last updated on

← PreviousRate Limits