Referencia

Errores

Los errores usan los códigos de estado HTTP y un cuerpo JSON. Los errores de validación indican qué campo ha fallado.

Estado	Significado
`400`	La petición no es válida: un campo no supera la validación, o la petición se rechaza (un agente desconocido en una campaña, nada que reintentar)
`401`	Falta la clave de API o es desconocida
`403`	El ajuste no está activado en tu cuenta (`declinedStopRatio`)
`404`	El recurso, o la entidad que indicaste, no existe
`409`	Un conflicto: elementos de dos entidades, un nombre o un id externo ya en uso, una entidad que aún contiene elementos, una herramienta todavía en uso
`422`	Un flujo de llamada referencia una herramienta que no existe, o da el nombre de otra herramienta a un nodo `forwardCall` con búsqueda de número
`5xx`	Un error del servidor: reintenta con un backoff progresivo y, si persiste, escribe a `support@callshift.ai`

Errores de validación

JSON

{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      { "code": "invalid_string", "path": ["contacts", 0, "email"], "message": "Invalid email" }
    ]
  }
}

Los errores de validación están en error. path localiza el campo, aquí el email del primer contacto.

Otros errores

JSON

{ "error": "Campaign not found" }

Algunos conflictos dan más detalles, para que puedas actuar en consecuencia:

Petición	Campo adicional
Crear una entidad cuyo id externo ya está en uso	`existingEntityId`: la entidad que lo tiene
Eliminar una entidad que contiene elementos	`usage`: sus `agents`, `phoneNumbers`, `webhooks`
Eliminar una herramienta en uso	`agents`: los agentes que la referencian