Manejo de errores

La API de Socios (Partner API) utiliza códigos de estado HTTP estándar y devuelve respuestas de error JSON consistentes.

Formato de respuesta de error

Todos los errores siguen esta estructura:

{
	"statusCode": 400,
	"message": "Validation failed",
	"error": "Bad Request"
}

Códigos de estado

Código	Error	Descripción
`400`	Bad Request	Cuerpo de solicitud inválido, campos requeridos faltantes o fallo de validación
`401`	Unauthorized	Credenciales de autenticación faltantes, inválidas o expiradas
`403`	Forbidden	Credenciales válidas pero permisos insuficientes para esta acción
`404`	Not Found	El recurso solicitado no existe
`409`	Conflict	Solicitud duplicada detectada (p. ej., clave de idempotencia duplicada con diferente carga útil)
`429`	Too Many Requests	Límite de velocidad excedido
`500`	Internal Server Error	Ocurrió un error inesperado en el servidor

Errores de validación

Para errores 400 causados por la validación de solicitudes, el campo message puede contener detalles sobre qué campos fallaron en la validación:

{
	"statusCode": 400,
	"message": [
		"products.0.productId must be a UUID",
		"products.0.startAt must be a valid ISO 8601 date",
		"payment.type must be one of: CARD, GOOGLE_PAY, APPLE_PAY, IDEAL, REVOLUT, BANCONTACT"
	],
	"error": "Bad Request"
}

Mejores prácticas

Siempre verifique el campo statusCode para determinar la categoría del error.
Para errores 401, verifique su clave API, la frescura de la marca de tiempo (dentro de 5 minutos), la unicidad del nonce y el cálculo de la firma.
Para errores 409 en la creación de pedidos, el pedido original ya fue procesado. Recupérelo usando la clave de idempotencia (idempotency key) o la referencia externa.
Para errores 500, reintente con retroceso exponencial (exponential backoff). Si el error persiste, contacte al soporte.