Manejo de errores

La API usa los códigos de estado HTTP estándar. Las respuestas correctas devuelven el cuerpo del recurso directamente. Los errores siguen RFC 9457 Problem Details for HTTP APIs (application/problem+json) con dos campos de extensión: un code de nivel superior sobre el que ramificas en tu código y un field de nivel superior (snake_case) en los errores de validación de un solo campo. Cuando fallan varios campos a la vez, field se sustituye por un array errors[] (un campo de extensión de Paymos, §3.2) con el desglose campo a campo.

{
  "type": "https://paymos.io/docs/errors/codes#insufficient_balance",
  "title": "Conflict",
  "status": 409,
  "detail": "Merchant balance is insufficient.",
  "code": "insufficient_balance"
}

Toda respuesta de error sigue RFC 9457 Problem Details for HTTP APIs y se entrega como Content-Type: application/problem+json.

Error único (la mayoría de las respuestas)

{
  "type": "https://paymos.io/docs/errors/codes#insufficient_balance",
  "title": "Conflict",
  "status": 409,
  "detail": "Merchant balance is insufficient.",
  "code": "insufficient_balance"
}

Validación de varios campos

Solo se emite cuando varios campos fallan la validación a la vez. El code de primer nivel siempre es validation_failed; el detalle por campo vive en errors[]:

{
  "type": "https://paymos.io/docs/errors/codes#validation_failed",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed.",
  "code": "validation_failed",
  "errors": [
    { "code": "field_required", "field": "currency", "message": "Currency is required." },
    { "code": "field_must_be_positive", "field": "amount", "message": "Amount must be > 0." }
  ]
}

Referencia de campos

Por qué códigos estructurados y no solo message

El texto de message y detail puede evolucionar entre versiones, localizarse o ampliarse con contexto. El contrato estable es code: una vez publicado, su semántica no cambia nunca. Usa code para la lógica programática y para la localización.

import { RateLimitError, ValidationError } from '@paymos/sdk';

try {
  await paymos.withdrawals.create(request);
} catch (error) {
  if (error instanceof ValidationError) {
    for (const item of error.errors) highlight(item.field, item.message);
  } else if (error instanceof RateLimitError) {
    scheduleRetry(error.retryAfterSeconds);
  }
  throw error;
}

use paymos::{ApiErrorKind, Error};

match paymos.withdrawals().create(&request).await {
    Ok(withdrawal) => process(withdrawal),
    Err(Error::Api(error)) if error.kind == ApiErrorKind::Validation => {
        for item in &error.errors {
            highlight(item.field.as_deref(), &item.message);
        }
    }
    Err(Error::Api(error)) if error.kind == ApiErrorKind::RateLimit => {
        schedule_retry(error.retry_after);
    }
    Err(error) => return Err(error),
}

Tipos de error

Cada estado llega dentro del formato de error con un title y un code legible por máquina. Un mismo estado puede cubrir varios escenarios: ramifica por el code, no por el estado.

Guía siempre la lógica de tu cliente por code y no por el estado HTTP: varios escenarios de negocio distintos comparten un mismo estado, y es el código que viaja en la respuesta el que los distingue.

Límites de peticiones

La API permite por defecto 30 peticiones por segundo por comercio, con un límite más estricto en POST /v1/invoices (5 peticiones/segundo). Se cuentan por comercio y por ventana de un segundo —todas tus claves de API consumen el mismo presupuesto— y los dos límites se pueden configurar por comercio. Al superarlo recibirás una respuesta 429 Too Many Requests con la cabecera Retry-After: 1.

{
  "type": "https://paymos.io/docs/errors/codes#rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded (30 req/sec). Retry after 1 second.",
  "code": "rate_limited"
}