Errores

Todos los errores llegan con el mismo envelope:

{
  "error": {
    "code": "DRIVER_BOUND_ELSEWHERE",
    "message": "El conductor ya está vinculado a otra flotilla en la plataforma",
    "requestId": "req_a1b2c3d4e5f6a7b8c9d0e1f2"
  }
}

code — identificador estable para programar contra él. El catálogo es cerrado y aditivo: nunca renombramos códigos.
message — explicación en español para humanos (puede cambiar; no programes contra él).
details — contexto opcional (p. ej. los campos inválidos en un VALIDATION).
requestId — guárdalo; también viaja en el header X-Request-Id de toda respuesta. Es lo primero que te pedirá soporte.

Códigos HTTP

HTTP	Cuándo
`400`	Entrada inválida (`VALIDATION`, `INVALID_FILE_TYPE`)
`401`	Llave faltante, inválida o revocada (`UNAUTHORIZED`)
`403`	Scope insuficiente, cuenta en revisión o plataforma no habilitada
`404`	El recurso no existe o no es tuyo — la API no distingue
`409`	Conflicto: duplicado global, estado incompatible, re-invitación
`413`	Archivo demasiado grande
`422`	La operación no procede por el estado del recurso o la plataforma
`429`	Límite de solicitudes — revisa `Retry-After`
`500`	Error interno (`INTERNAL`) — reporta el `requestId`
`503`	La plataforma (didi/indrive) no está disponible (`PLATFORM_UNAVAILABLE`)

Catálogo de códigos

Código	HTTP	Significado
`VALIDATION`	400	Payload inválido — `details` trae los campos
`UNAUTHORIZED`	401	Problema con la llave
`FORBIDDEN` / `INSUFFICIENT_SCOPE`	403	Sin permiso / sin scope
`TENANT_PENDING`	403	Tu cuenta Credikul sigue en revisión
`PLATFORM_NOT_ENABLED`	403	Función no habilitada (p. ej. conductores indrive en v1)
`NOT_FOUND`	404	Recurso inexistente o de otra flotilla
`CONFLICT`	409	Duplicado (placa/VIN/WhatsApp globales) o estado incompatible
`ALREADY_INVITED`	409	La plataforma ya tenía una invitación activa
`ALREADY_REGISTERED`	409	El recurso ya estaba registrado
`DRIVER_BOUND_ELSEWHERE`	409	El conductor pertenece a otra flotilla en la plataforma
`DRIVER_NOT_ON_PLATFORM`	422	El conductor no existe en la plataforma
`INVALID_PHONE`	422	Teléfono inválido para la plataforma
`CITY_REQUIRED`	422	Falta la ciudad del vehículo para el alta didi
`FILE_TOO_LARGE`	413	Documento > 4 MB
`INVALID_FILE_TYPE`	400	Formato de archivo no aceptado
`RATE_LIMITED`	429	Límite de solicitudes excedido
`PLATFORM_REJECTED`	422	La plataforma rechazó la operación
`PLATFORM_UNAVAILABLE`	503	La plataforma no responde — reintenta
`INTERNAL`	500	Error de Credikul

Reintentos

Reintenta con retroceso exponencial: 429 (respeta Retry-After), 500, 503.
No reintentes a ciegas los 4xx restantes — el resultado será el mismo.
Las mutaciones son seguras de repetir: re-registrar o re-invitar responde 200 idempotente, y los duplicados responden 409 en lugar de crear dobles.