Errores · Documentación API Nexcar

Formato#

Todos los errores usan el mismo envelope JSON:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "case_id no es un UUID válido",
    "details": { "field": "case_id" }
  }
}

code es estable: tu sistema debe decidir el comportamiento con base en él.
message es legible para humanos y puede cambiar (no lo parsees).
details es opcional y específico del error.

Códigos comunes#

4xx — errores del cliente#

HTTP	`code`	Significado	Acción sugerida
`400`	`MISSING_PARAMETER`	Falta un campo requerido	Revisa el cuerpo del request
`400`	`VALIDATION_ERROR`	Un campo tiene formato inválido	Revisa el detalle en `details.field`
`400`	`DUPLICATE_INTERNAL_ID`	Ya existe un caso con ese `internal_id`	Reusa el `case_id` que devolvemos en `details`
`401`	`UNAUTHORIZED`	Credenciales ausentes o expiradas	Renueva tu token o revisa la API key
`401`	`INVALID_CREDENTIALS`	Credenciales inválidas	Verifica que estés usando la key correcta del ambiente
`403`	`FORBIDDEN`	Sin permiso sobre el recurso	Contacta a soporte para revisar tu acceso
`404`	`RESOURCE_NOT_FOUND`	Caso o documento inexistente	Verifica el ID o si fue dado de baja
`409`	`CONFLICT`	El recurso está en un estado incompatible con la operación	Consulta el estado actual y reintenta
`413`	`PAYLOAD_TOO_LARGE`	Archivo > 20 MB	Reduce el tamaño antes de reintentar
`415`	`UNSUPPORTED_MEDIA_TYPE`	MIME no soportado	Usa un MIME del catálogo
`422`	`INVALID_STATUS`	El `status` no es válido para tu catálogo	Usa un valor del catálogo configurado
`429`	`RATE_LIMITED`	Excediste el límite de peticiones	Aplica backoff y reintenta

5xx — errores del servidor#

HTTP	`code`	Significado
`500`	`INTERNAL_ERROR`	Error inesperado de Nexcar
`502`	`UPSTREAM_ERROR`	Falla de un servicio externo (OCR, almacenamiento)
`503`	`SERVICE_UNAVAILABLE`	Mantenimiento en curso

Para 5xx, reintenta con backoff exponencial. Si persiste más de 5 minutos, escríbenos a soporte@nexcar.mx con el request_id que viene en los encabezados de respuesta.