Formato de errores
Toda la API BSP usa un único sobre de error, inspirado en el formato de Meta:
{
"error": {
"code": 400,
"error_data": {
"details": "descripción del error"
}
}
}Códigos de error
Errores de cliente (4xx)
| Código | Significado |
|---|---|
400 | Request inválido: body mal formado, parámetros faltantes, validación fallida |
401 | No autenticado: token faltante o inválido |
403 | No autorizado: sin BSP_CN para operar sobre otro cliente, o DID fuera de la jerarquía |
404 | Recurso no encontrado (template inexistente, rate no disponible) |
413 | Multipart excede el tamaño máximo permitido |
Errores de servicios externos (5xx)
Cuando la API no puede comunicarse con un servicio externo (por ejemplo Meta), el error nunca expone detalles de infraestructura:
| Código | Detalle |
|---|---|
502 | upstream service unavailable — el servicio externo no respondió |
504 | upstream timeout — el servicio externo excedió el tiempo de espera |
Regla de oro: los errores con un código de respuesta del servicio externo se preservan (ej: un
429 de Meta se devuelve como 429). Los fallos genéricos sin respuesta siempre colapsan a 502.Ejemplos comunes
Validación fallida
{
"error": {
"code": 400,
"error_data": {
"details": "did is required"
}
}
}URL de header media no HTTPS
{
"error": {
"code": 400,
"error_data": {
"details": "URL must use https scheme"
}
}
}Header media con header_source y header_handle simultáneos
{
"error": {
"code": 400,
"error_data": {
"details": "header_source and header_handle are mutually exclusive for media headers"
}
}
}Servicio externo inalcanzable
{
"error": {
"code": 502,
"error_data": {
"details": "upstream service unavailable"
}
}
}Errores crudos de Meta
Cuando la API de Meta devuelve un error (ej: rechazo por política de categoría), la plataforma lo pasa tal cual al cliente, preservando el code y los detalles originales de Meta.
Para más información sobre errores de Meta, consultá la documentación de errores de Meta.