monivio
Skúsiť

Chybové odpovede

HTTP kódy a tvar chybového JSON-u, ktoré API vracia.

Všetky chyby majú konzistentný JSON tvar. Status code určuje kategóriu, error.code konkrétnu príčinu, a error.message je human-readable popis vhodný na log.

Tvar chybovej odpovede

Response bodyjson
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Contact con_aaaaaaaaaaaaaaaaaaaaaaaa not found"
  }
}

Validation errors (422)

Pri VALIDATION_ERROR navyše dostaneš field-by-field detail z Zod-u v poli issues:

Response 422json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "issues": [
        {
          "path": "email",
          "message": "Must be a valid email address"
        },
        {
          "path": "billing_country",
          "message": "Must be a 2-letter ISO 3166-1 alpha-2 code"
        },
        {
          "path": "line_items.0.quantity",
          "message": "Number must be greater than 0"
        }
      ]
    }
  }
}

HTTP status codes

  • • 200 OK - úspešné GET/PATCH/PUT
  • • 201 Created - úspešné POST (resource vytvorený)
  • • 204 No Content - úspešný DELETE alebo akcia bez obsahu
  • • 400 Bad Request - nesprávne formátovaný JSON v body
  • • 401 Unauthorized - chýbajúci, neplatný, expired alebo revoked API kľúč
  • • 402 Payment Required - prekročená mesačná kvóta plánu
  • • 403 Forbidden - kľúč existuje ale nemá scope (alebo má read_only typ pri write request)
  • • 404 Not Found - entita neexistuje alebo patrí inej organizácii (RLS politika ju maskuje)
  • • 409 Conflict - stav nepovoľuje akciu (napr. mazanie inviced dokumentu)
  • • 413 Payload Too Large - upload prekročil 5 MB
  • • 422 Unprocessable Entity - body neprešiel Zod validáciou
  • • 429 Too Many Requests - rate limit prekročený
  • • 500 Internal Server Error - chyba na našej strane (logujeme do Sentry)
  • • 503 Service Unavailable - plánovaná údržba alebo dependency outage

Kompletný zoznam error.code hodnôt nájdeš v Reference → Chybové kódy.

Error handling pattern

TypeScripttypescript
async function callMonivio(path: string) {
  const res = await fetch(`https://monivio.sk/api/v1${path}`, {
    headers: { Authorization: `Bearer ${process.env.MONIVIO_API_KEY!}` },
  });

  if (res.ok) return res.json();

  const { error } = await res.json();

  // Retryable: rate limit + transient server errors.
  if (res.status === 429 || res.status >= 500) {
    const retryAfter = Number(res.headers.get("Retry-After")) || 5;
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return callMonivio(path);
  }

  // Permanent: bubble up so the caller can handle 401/403/404 explicitly.
  throw new MonivioError(error.code, error.message, res.status);
}