Errors

The envelope#

Every error response with a JSON body looks like this:

{
  "error": {
    "code": "quote_expired",
    "message": "The quote has expired; ask for a new one.",
    "request_id": "req_01JB8X2Q4M7Z3V9K5T1N6R0P2W"
  }
}

• code is stable and machine-readable. Branch on it.
• message explains the error to a person. It may change at any time, so don't parse it.
• request_id is also in the MK-Request-Id header of every response, successful or not. Log it, and quote it when you contact us.

A 2xx status means success; anything else carries this envelope. GET /v1/giftcards/{id}/pdf answers application/pdf on success and JSON on errors.

Error codes#

Each endpoint's reference page lists the codes it can return.

Handling errors#

The SDKs turn every error into an ApiError with status, code, message and requestId (request_id in Python), plus retryAfter (retry_after) when the response had a Retry-After header. Subclasses group the statuses:

import { ApiError, Myntkaup, RateLimitError } from "@myntkaup/api";

const client = new Myntkaup();

try {
  const trade = await client.buy({ asset: "BTC", quoteAmount: "25.00" });
  console.log(trade.status);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.warn(`Slow down; retry in ${error.retryAfter} s (${error.requestId})`);
  } else if (error instanceof ApiError && ["price_moved", "quote_expired"].includes(error.code)) {
    // The market moved: decide whether to try again with a new quote.
  } else {
    throw error;
  }
}

import myntkaup
from myntkaup import Myntkaup

client = Myntkaup()

try:
    trade = client.buy(asset="BTC", quote_amount="25.00")
    print(trade["status"])
except myntkaup.RateLimitError as error:
    print(f"Slow down; retry in {error.retry_after} s ({error.request_id})")
except myntkaup.ApiError as error:
    if error.code not in ("price_moved", "quote_expired"):
        raise
    # The market moved: decide whether to try again with a new quote.

Which errors to retry#

• Retry after waiting: 429 rate_limited, 429 too_many_concurrent_requests, 503 overloaded and 503 service_unavailable (honour Retry-After), and 502 and 504.
• Retry a POST only with the same Idempotency-Key. After a 502, 504 or a dropped connection the request may have gone through; the same key returns the first result instead of doing it twice. See Idempotency.
• Wait, then retry with the same key: 409 idempotency_in_progress.
• Don't retry as is: every other 4xx. Change the request (or the key, or the quote) first.
• Never retry: 429 key_suspended. Stop and fix the client.

The SDKs handle the first two cases for you: a GET is retried on 429 (except key_suspended), 502, 503, 504 and network errors, and a POST only when it carries an Idempotency-Key. They retry at most twice by default, with exponential backoff and jitter, and honour Retry-After.