Błędy

Koperta

Każdy błąd, bez wyjątku, ma ten sam kształt:

{
  "error": {
    "code": "API_KEY_INSUFFICIENT_SCOPE",
    "message": "Klucz API nie ma wymaganych uprawnień",
    "details": {
      "requiredScope": "tasks.write",
      "availableScopes": ["tasks.read", "users.read"]
    }
  }
}

VALIDATION_ERROR

Wyjątek od reguły „details to obiekt": przy VALIDATION_ERROR details jest tablicą obiektów { field, message }, po jednym na każde pole, które nie przeszło walidacji.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Walidacja nie powiodła się",
    "details": [
      { "field": "title", "message": "Tytuł jest wymagany" },
      { "field": "priority", "message": "Nieprawidłowa wartość. Oczekiwano 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'" }
    ]
  }
}

field jest ścieżką z kropkami do miejsca w ciele żądania, np. context.variables.session_id.

Kody statusu HTTP

404 na zasobie z innego workspace wygląda identycznie jak 404 na identyfikatorze, który nie istnieje. To celowe: API nie jest wyrocznią istnienia.

Katalog kodów

401 — uwierzytelnianie

Poza rozróżnieniem „wygasł" / „unieważniony" 401 jest celowo nieinformacyjne — żeby nie dało się nim sondować, które klucze istnieją.

403 — uprawnienia

429 — limity

Szczegóły limitów: Limity zapytań.

400 — żądanie odrzucone

404 — nie znaleziono

409 — konflikt

410 — zasób wygasł

422 — walidacja i reguły biznesowe

502 — usługa niżej

503 — chwilowa niedostępność

500 — błąd po naszej stronie

Wszystkie znaczą to samo — operacja padła u nas — ale kod mówi, która. Ponów z wykładniczym odczekaniem; jeśli wraca, zgłoś to.

BOTS_FETCH_FAILED, BOT_FETCH_FAILED, BOT_CREATE_FAILED, BOT_UPDATE_FAILED, BOT_CONFIG_FETCH_FAILED, BOT_CONFIG_UPDATE_FAILED, BOT_CONFIG_PUBLISH_FAILED, BOT_CONFIG_ROLLBACK_FAILED, BOT_CONFIG_SNAPSHOTS_FETCH_FAILED, BOT_PROCEDURES_FETCH_FAILED, BOT_PROCEDURES_COMPILE_INVALID, BOT_PROCEDURE_FETCH_FAILED, BOT_PROCEDURE_CREATE_FAILED, BOT_PROCEDURE_UPDATE_FAILED, BOT_PROCEDURE_DELETE_FAILED, BOT_PROCEDURE_REORDER_FAILED, BOT_WORKFLOWS_FETCH_FAILED, BOT_WORKFLOW_FETCH_FAILED, BOT_WORKFLOW_CREATE_FAILED, BOT_WORKFLOW_UPDATE_FAILED, BOT_WORKFLOW_DELETE_FAILED, BOT_WORKFLOW_ACTIVATE_FAILED, BOT_WORKFLOW_DEACTIVATE_FAILED, BOT_WORKFLOW_VALIDATION_REQUEST_FAILED, BOT_SESSION_CREATE_FAILED, BOT_SESSION_TRANSCRIPT_FETCH_FAILED, EXTERNAL_API_BOT_SESSIONS_FETCH_FAILED, LOCATIONS_FETCH_FAILED, LOCATION_CREATE_FAILED, LOCATION_UPDATE_FAILED, PHONE_NUMBERS_FETCH_FAILED, PHONE_NUMBER_ATTACH_BOT_FAILED, MODEL_CATALOG_FETCH_FAILED, WEBHOOK_EVENT_TYPES_FETCH_FAILED, TASKS_FETCH_FAILED, TASK_CREATE_FAILED, TASK_UPDATE_FAILED, TASK_DELETE_FAILED, USERS_FETCH_FAILED, TAGS_FETCH_FAILED, EXTERNAL_API_CALLS_FETCH_FAILED, CONTACT_REQUESTS_FETCH_FAILED, CONTACT_REQUEST_CREATE_FAILED, TICKET_CREATE_FAILED, TICKET_UPDATE_FAILED, EXTERNAL_API_TICKETS_FETCH_FAILED, WEBHOOK_ENDPOINTS_FETCH_FAILED, WEBHOOK_ENDPOINT_CREATE_FAILED, WEBHOOK_ENDPOINT_UPDATE_FAILED, WEBHOOK_ENDPOINT_DELETE_FAILED, WEBHOOK_DELIVERIES_FETCH_FAILED, WEBHOOK_DELIVERY_REDELIVER_FAILED.

Obsługa błędów w kodzie

Ponawiaj 429 zawsze. 5xx ponawiaj tylko dla operacji bezpiecznych (GET, HEAD) albo takich, które sam zabezpieczyłeś kluczem idempotencji (np. POST /bot-sessions z idempotencyKey) — POST bez takiej gwarancji mógł się wykonać po stronie serwera, zanim dostałeś błąd, a ponowienie założy duplikat. Nie ponawiaj 4xx — one nie przejdą same z siebie.

async function medifloFetch(url, options = {}, { maxRetries = 3, idempotent = false } = {}) {
  const method = (options.method ?? 'GET').toUpperCase()
  const safeToRetry = idempotent || method === 'GET' || method === 'HEAD'

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options)
    if (response.ok) return response.json()

    const body = await response.json().catch(() => null)
    const code = body?.error?.code

    if (response.status === 429) {
      const retryAfter = Number(response.headers.get('Retry-After') ?? 1)
      await new Promise(r => setTimeout(r, retryAfter * 1000))
      continue
    }

    if (response.status >= 500 && safeToRetry) {
      await new Promise(r => setTimeout(r, 2 ** attempt * 1000))
      continue
    }

    // 4xx — rozgałęź się na kodzie, nie ponawiaj.
    switch (code) {
      case 'API_KEY_EXPIRED':
      case 'API_KEY_REVOKED':
        throw new Error('Zrotuj klucz API')
      case 'API_KEY_INSUFFICIENT_SCOPE':
        throw new Error(`Brakuje zakresu: ${body.error.details.requiredScope}`)
      case 'VALIDATION_ERROR':
        throw new Error(
          body.error.details.map(d => `${d.field}: ${d.message}`).join('; ')
        )
      default:
        throw new Error(`${response.status} ${code ?? 'UNKNOWN'}`)
    }
  }
  throw new Error('Wyczerpano ponowienia')
}

Przykład z curl, który pokazuje samą kopertę:

curl -s -o /dev/null -w '%{http_code}\n' \
  https://app.mediflo.ai/api/external/v1/bots \
  -H "Authorization: Bearer mflo_live_..."