Dokumentacja / Szybki start

Obsługa błędów

3 min czytania

Ten przewodnik wyjaśnia odpowiedzi błędów z MailingAPI i jak je prawidłowo obsługiwać.

Format odpowiedzi błędu

Wszystkie błędy mają spójny format JSON:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid email address format",
    "field": "to",
    "details": {
      "value": "not-an-email",
      "expected": "valid email address"
    }
  }
}

Pola:

  • code — Identyfikator błędu do odczytu maszynowego
  • message — Opis czytelny dla człowieka
  • field — (opcjonalne) Które pole spowodowało błąd
  • details — (opcjonalne) Dodatkowy kontekst

Kody statusu HTTP

Kod Znaczenie Kiedy występuje
200 OK Żądanie udane
201 Created Zasób utworzony
202 Accepted Operacja async w kolejce
400 Bad Request Nieprawidłowe parametry
401 Unauthorized Brak lub nieprawidłowy klucz API
403 Forbidden Prawidłowy klucz, niewystarczające uprawnienia
404 Not Found Zasób nie istnieje
409 Conflict Zasób już istnieje
422 Unprocessable Poprawna składnia, ale błąd semantyczny
429 Too Many Requests Przekroczony limit żądań
500 Server Error Coś poszło nie tak po naszej stronie

Typowe kody błędów

Błędy autentykacji (401)

{"error": {"code": "unauthorized", "message": "Invalid or missing API key"}}

Przyczyny:

  • Brak nagłówka Authorization
  • Źle sformowany bearer token
  • Nieprawidłowy lub unieważniony klucz API

Rozwiązanie: Sprawdź czy klucz API jest poprawny i aktywny.

Błędy uprawnień (403)

{"error": {"code": "forbidden", "message": "API key lacks 'manage' permission"}}

Przyczyny:

  • Klucz nie ma wymaganego poziomu uprawnień
  • Próba dostępu do zasobów innej organizacji
  • Adres from nie pasuje do domeny klucza

Rozwiązanie: Użyj klucza z odpowiednimi uprawnieniami lub popraw adres from.

Błędy walidacji (400)

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "errors": [
      {"field": "to", "message": "is required"},
      {"field": "html", "message": "must be valid HTML"}
    ]
  }
}

Rozwiązanie: Sprawdź tablicę errors i popraw każde pole.

Błędy rate limit (429)

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "retry_after": 60
  }
}

Rozwiązanie: Poczekaj retry_after sekund, potem ponów z exponential backoff.

Błędy zasobów (404, 409)

{"error": {"code": "not_found", "message": "Message not found"}}
{"error": {"code": "conflict", "message": "Domain already exists"}}

Rozwiązanie: Zweryfikuj ID zasobu lub sprawdź duplikaty.

Obsługa błędów w kodzie

Python

import requests
from requests.exceptions import HTTPError

try:
    response = requests.post(
        "https://api.mailingapi.com/v1/messages/send",
        headers={"Authorization": f"Bearer {api_key}"},
        json=payload
    )
    response.raise_for_status()
    result = response.json()

except HTTPError as e:
    error = e.response.json().get("error", {})

    if e.response.status_code == 401:
        # Ponowna autentykacja lub sprawdzenie klucza
        handle_auth_error()
    elif e.response.status_code == 429:
        # Respektuj rate limit
        retry_after = error.get("retry_after", 60)
        time.sleep(retry_after)
        # Ponów żądanie
    elif e.response.status_code == 400:
        # Zaloguj błędy walidacji
        logger.error(f"Validation failed: {error}")
    else:
        # Nieoczekiwany błąd
        logger.error(f"API error: {error}")
        raise

JavaScript

async function sendEmail(payload) {
  try {
    const response = await fetch('https://api.mailingapi.com/v1/messages/send', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      const { error } = await response.json();

      switch (response.status) {
        case 401:
          throw new AuthenticationError(error.message);
        case 429:
          const retryAfter = error.retry_after || 60;
          await sleep(retryAfter * 1000);
          return sendEmail(payload); // Ponów
        case 400:
          throw new ValidationError(error.message, error.errors);
        default:
          throw new APIError(error.message, error.code);
      }
    }

    return response.json();

  } catch (error) {
    console.error('Failed to send email:', error);
    throw error;
  }
}

Strategia ponawiania

Dla błędów przejściowych (429, 500, 502, 503, 504), implementuj exponential backoff:

import time
import random

def send_with_retry(payload, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = send_email(payload)
            return response
        except TransientError as e:
            if attempt == max_retries - 1:
                raise

            # Exponential backoff z jitter
            delay = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)

Rób:

  • Ponawiaj przy 429, 500, 502, 503, 504
  • Używaj exponential backoff
  • Dodaj losowy jitter by uniknąć thundering herd
  • Ustaw maksymalną liczbę ponowień

Nie rób:

  • Nie ponawiaj przy 400, 401, 403, 404 — nie zmienią się
  • Nie ponawiaj natychmiast bez opóźnienia
  • Nie ponawiaj w nieskończoność

Idempotencja

Dla bezpiecznego ponawiania używaj kluczy idempotencji:

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{...}'

Jeśli ponowisz żądanie z tym samym Idempotency-Key, otrzymasz oryginalną odpowiedź zamiast tworzyć duplikat.

Wskazówki do debugowania

  1. Sprawdź kod błędu — Pole code mówi dokładnie co poszło nie tak
  2. Spójrz na pole — Dla błędów walidacji, field wskazuje problem
  3. Przeczytaj wiadomość — Czytelne dla człowieka wyjaśnienie
  4. Sprawdź logi żądań — W dashboardzie pod Logi → Żądania API
  5. Waliduj lokalnie — Użyj /v1/messages/analyze by sprawdzić treść przed wysyłką

Uzyskanie pomocy

Jeśli utkniesz:

Następne kroki

Teraz rozumiesz jak obsługiwać błędy. Naucz się wysyłać emaile w szczegółach.

Wysyłanie emaili →