Errores

SIP Caller usa los códigos de estado HTTP estándar para indicar si una solicitud fue exitosa. Los códigos del rango 2xx indican éxito, los códigos del rango 4xx indican un problema con la solicitud (por ejemplo, un campo faltante o un registro que no existe), y los códigos del rango 5xx indican un problema del lado de SIP Caller.

Formato de las respuestas de error

Las respuestas de error tienen un cuerpo JSON que sigue el estándar Problem Details:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "One or more errors occurred.",
  "status": 404,
  "detail": "Campaign with id '01a0dedd-b9a2-729d-8e0a-4e3ad9197aea' not found",
  "instance": "/v1/accounts/ACCOUNT_ID/campaigns/01a0dedd-b9a2-729d-8e0a-4e3ad9197aea",
  "traceId": "0HN6QKQ1B2F3G:00000001"
}

Campo	Descripción
type	Una URL que identifica el tipo de error, según el código de estado HTTP.
title	Un resumen breve y genérico del error.
status	El código de estado HTTP.
detail	Una explicación legible de este error específico. No está presente en los errores de validación.
instance	La ruta de la solicitud que causó el error.
traceId	Un identificador único de la solicitud. Inclúyelo al contactar a soporte por un error.
errors	Solo en los errores 400 y 409: la lista de mensajes de cada campo no válido, como se describe más abajo.

Los mensajes de detail y errors tienen como objetivo ayudar a los desarrolladores a entender el problema. No los analices en tu código, ya que su texto puede cambiar: usa el código de estado HTTP en su lugar.

Errores de validación

Cuando uno o más campos de la solicitud no son válidos, la API devuelve un error 400 Bad Request con un objeto errors. Cada clave es el nombre de un campo no válido (usando puntos para los campos anidados), y cada valor es la lista de problemas encontrados:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "instance": "/v1/accounts/ACCOUNT_ID/campaigns",
  "errors": {
    "name": ["Value must not be empty."],
    "maxAttempts": ["Value must be between 1 and 9."]
  },
  "traceId": "0HN6QKQ1B2F3G:00000002"
}

Todos los campos no válidos se informan a la vez, para que puedas corregirlos en un solo paso. Los errores en los parámetros de consulta filter, sort y range se informan de la misma manera, bajo esas claves.

Códigos de estado HTTP

Código	Significado
200 OK	La solicitud fue exitosa.
201 Created	Se creó el recurso. La respuesta contiene el nuevo recurso.
400 Bad Request	La solicitud no es válida: falta un campo obligatorio, un valor tiene un formato incorrecto o está fuera de rango, o el JSON está mal formado. Consulta el campo errors o detail.
401 Unauthorized	No se proporcionó una API Key válida. Consulta Autenticación.
403 Forbidden	La API Key no tiene permiso para realizar la operación.
404 Not Found	El recurso no existe, o no pertenece a la cuenta.
408 Request Timeout	El cuerpo de la solicitud se envió demasiado lento.
409 Conflict	La solicitud entra en conflicto con el estado actual del recurso. Por ejemplo, un nombre que debe ser único ya está en uso, o un recurso no se puede eliminar porque se está usando.
412 Precondition Failed	Otra persona modificó el recurso desde la última vez que lo leíste. Consulta Actualizaciones concurrentes más abajo.
413 Payload Too Large	El cuerpo de la solicitud supera el tamaño máximo de 20 MB.
429 Too Many Requests	Se enviaron demasiadas solicitudes en poco tiempo. Consulta Límites de solicitudes.
500 Internal Server Error	Algo salió mal del lado de SIP Caller. Nuestro equipo recibe una notificación automáticamente. Puedes reintentar la solicitud más tarde.

Actualizaciones concurrentes

Para evitar que se pierdan cambios cuando distintos usuarios o aplicaciones editan el mismo recurso al mismo tiempo, las solicitudes de actualización (por ejemplo Actualizar una campaña) requieren un campo lastUpdatedAt. Debe contener el valor de updatedAt del recurso, tal como se devolvió la última vez que lo obtuviste, creaste o editaste.

Si el recurso se modificó mientras tanto, su valor de updatedAt ya no coincide, y la actualización se rechaza con un error 412 Precondition Failed:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.13",
  "title": "One or more errors occurred.",
  "status": 412,
  "detail": "Update aborted to prevent 'lost update' problem; retry with correct 'lastUpdatedAt' value",
  "instance": "/v1/accounts/ACCOUNT_ID/blackLists/BLACK_LIST_ID",
  "traceId": "0HN6QKQ1B2F3G:00000003"
}

Cuando recibas este error, vuelve a obtener el recurso, aplica tus cambios sobre la versión más reciente, y envía la actualización con el nuevo valor de lastUpdatedAt.

Manejo de errores

Recomendamos el siguiente enfoque en tu integración:

• Errores 4xx (excepto 429): no reintentes la misma solicitud, ya que volverá a fallar. Registra la respuesta, incluido el traceId, y corrige la solicitud.
• Errores 429: espera la cantidad de segundos indicada en el encabezado Retry-After, y vuelve a intentarlo.
• Errores 5xx y errores de red: reintenta con un retroceso exponencial (por ejemplo, después de 1, 2, 4 y 8 segundos). Ten cuidado al reintentar solicitudes que crean recursos o agregan números, ya que el primer intento puede haber sido exitoso antes del error: verifica el estado actual antes de reintentar.