Identifica la causa de una solicitud fallida
Comprueba el estado HTTP, el código de error y la respuesta. Revisa la versión de la API, el proxy y la sesión antes de continuar.

Buscar códigos de error
31 códigos de error oficiales y 9 ejemplos de suplementos de orientación, organizados por tipo de falla. Las sugerencias de procesamiento deben combinarse con la versión y el mensaje reales.
No se encontró ninguna coincidencia. Mantenga el código y el mensaje reales,Ver la documentación de respuesta más recienteoPóngase en contacto con el soporte técnico。
Parámetros y cuenta
| Código de error/fuente del documento | Sugerencias para solucionar problemas | Siguiente paso |
|---|---|---|
PARAMS_ERRORTodas las versionesdocumento de respuesta | Verifique si faltan campos, tipos y rangos, corríjalos por mensaje; Los valores de tiempo de espera ilegales en V2 también pueden desencadenar este error. | Arreglar configuración |
USER_AGENT_INVALIDv1/v2/v2sdocumento de respuesta | Primero elimine el x-cb-ua no resuelto o regrese a la huella digital predeterminada y verifique la versión actual del rango de soporte de UA. | Arreglar configuración |
APIKEY_INVALIDTodas las versionesdocumento de respuesta | Confirme que el entorno operativo real haya leído la clave válida, verifique el estado deshabilitado o reiniciado y no lo resuelva cambiando la IP. | Deja de reintentar |
INSUFFICIENT_BALANCETodas las versionesdocumento de respuesta | Consultar el saldo de puntos API y el tiempo de vencimiento; El tráfico proxy es otro uso y no pueden ser reemplazados entre sí. | Deja de reintentar |
HOSTNAME_IS_FORBIDDENTodas las versionesdocumento de respuesta | Verifique el nombre de dominio de destino y los permisos de acceso, y conserve el mensaje; No intente eludir las restricciones de acceso explícitas. | Confirmación manual |
HOSTNAME_IS_NULLTodas las versionesdocumento de respuesta | Complete x-cb-host, complete solo el nombre del host de destino y los puertos necesarios, sin protocolo, ruta o parámetros de consulta. | Arreglar configuración |
HOSTNAME_IS_INVALIDConfirmar mediante devolución realSuplemento de la guía de IA | Verifique el host y el puerto de destino, manteniendo la ruta y los parámetros de consulta en la URL de solicitud API. | Arreglar configuración |
PART_ERRORConfirmar mediante devolución realSuplemento de la guía de IA | Verifique el formato de número entero de x-cb-part y el rango real disponible de la cuenta, y no reutilice particiones aleatoriamente para otras tareas. | Arreglar configuración |
INVALID_SITEKEYConfirmar mediante devolución realSuplemento de la guía de IA | Verifique la clave del sitio Turnstile del destino y confirme que la solicitud también contiene el marcador de posición [cf_token]. | Arreglar configuración |
Proxy, red y certificados
| Código de error/fuente del documento | Sugerencias para solucionar problemas | Siguiente paso |
|---|---|---|
PROXY_ERRORTodas las versionesdocumento de respuesta | Verifique la cuenta del proxy, el protocolo, el puerto, el período de disponibilidad y el tráfico, y distinga los errores devueltos por el proxy de los errores devueltos por el sitio de destino. | Ver enlace |
PROXY_FORMAT_ERRORTodas las versionesdocumento de respuesta | Verifique el formato del proxy de acuerdo con el documento de parámetros de solicitud y confirme que la versión utilizada acepte el protocolo; reescribir el prefijo no significa convertir el protocolo. | Arreglar configuración |
PROXY_IS_FORBIDDENTodas las versionesdocumento de respuesta | Confirme que el servicio puede utilizar la dirección de proxy y utilice en su lugar un proxy válido y permitido; no envíe la misma dirección prohibida repetidamente. | Deja de reintentar |
CONNECTION_ERRORTodas las versionesdocumento de respuesta | Distinga la conexión de la máquina local a API, API al proxy y al destino, y verifique la dirección y la línea según el mensaje. | Ver enlace |
DNS_ERRORTodas las versionesdocumento de respuesta | Primero confirme si el nombre de dominio fallido es el nombre de dominio local API, el nombre de dominio proxy o el nombre de dominio de destino, y verifique la resolución y el tiempo de espera respectivamente. | Ver enlace |
TLS_ERRORTodas las versionesdocumento de respuesta | Verifique los protocolos de destino y proxy, la hora del sistema y la cadena de certificados; Se corrige que no se desactive la verificación TLS de forma predeterminada. | Ver enlace |
CERT_ERRORTodas las versionesdocumento de respuesta | Verifique la cadena de certificados, los certificados intermedios de proxy y las direcciones de destino; no atribuya simplemente las fallas de los certificados a problemas de propiedad intelectual. | Ver enlace |
REQUEST_ERRORTodas las versionesdocumento de respuesta | Los tiempos de espera, los rechazos y las interrupciones de conexión se distinguen por mensaje, y solo los fallos temporales seguros y reproducibles tienen reintentos limitados. | Reintentos limitados |
EOF_ERRORTodas las versionesdocumento de respuesta | Compruebe si la conexión se cerró prematuramente, si el proxy ha caducado, si el archivo está completo y no trate las respuestas truncadas como exitosas. | Ver enlace |
RESOLVE_PROXYConfirmar mediante devolución realSuplemento de la guía de IA | Verifique el DNS del host proxy con el entorno operativo real y registre el mensaje de falla de resolución. | Ver enlace |
PROXY_CONNECT_ABORTEDConfirmar mediante devolución realSuplemento de la guía de IA | Verifique la autenticación del proxy, el período de validez y los motivos de interrupción de la conexión, y solo vuelva a intentarlo dentro del presupuesto después de una falla temporal. | Ver enlace |
TIMEOUT_ERRORConfirmar mediante devolución realSuplemento de la guía de IA | Distinga entre espera del cliente, tiempo de espera API y respuesta objetivo, y confirme el presupuesto total de la tarea antes de aumentar el tiempo de espera. | Comprobar tiempo de espera |
SSL_ERRORConfirmar mediante devolución realSuplemento de la guía de IA | Verifique las cadenas y protocolos de certificados de destino, proxy y cliente y no deshabilite la verificación de certificados de forma predeterminada. | Ver enlace |
Verificaciones y sesiones
| Código de error/fuente del documento | Sugerencias para solucionar problemas | Siguiente paso |
|---|---|---|
UNSUPPORTED_CAPTCHATodas las versionesdocumento de respuesta | Mantenga el tipo de verificación y la respuesta de desensibilización, comuníquese con el soporte técnico después de confirmar el límite de soporte y no vuelva a intentarlo infinitamente. | Deja de reintentar |
CLOUDFLARE_PREMIUMv1documento de respuesta | La documentación enumera consejos para que V1 encuentre escudos de cinco segundos; cambie a V2 después de verificar los objetivos y prepárese para proxies fijos o fijos. | Ajustar versión |
CLOUDFLARE_CHALLENGE_TIMEOUTv2documento de respuesta | Verifique la estabilidad de salida, la validez del proxy y los tiempos de espera de dos niveles; Vuelva a intentarlo con el presupuesto y verifique con nuevas sesiones si es necesario. | Reintentos limitados |
DATADOME_CHALLENGE_TIMEOUTv2documento de respuesta | Verifique los proxies fijos/fijos y desafíe los presupuestos de tiempo; las fallas persistentes conservan los ID de las solicitudes y tienen éxito sin comprometerse con demoras. | Reintentos limitados |
DATADOME_ACCESS_DENIEDv2documento de respuesta | Verifique los permisos de destino, la región y la reputación de exportación; cambiar las exportaciones permitidas según la base y restablecer la sesión simultáneamente. | Confirmación manual |
CHALLENGE_LOCK_TIMEOUTv2documento de respuesta | Verifique si todavía hay desafíos esperando para la misma sesión; wait-lock está en desuso en la documentación de parámetros actual. | Cola primero |
CHALLENGE_LOCK_OCCUPIEDv2documento de respuesta | Espere a que finalice el primer desafío de la misma sesión para reducir la simultaneidad; Las tareas independientes utilizan particiones independientes disponibles. | Cola primero |
BYPASS_ERRORv2documento de respuesta | Lea primero el mensaje y concéntrese en comprobar si el proxy cambia durante la sesión; Primero cree una nueva sesión y la fuerza no se utiliza como configuración predeterminada. | Consultar sesión |
PROXY_NON_STICKYv2documento de respuesta | Esta verificación es sólo para el proxy Scrapingbypass API. Utilice una salida fija/fija válida en su lugar y cree una nueva sesión de autenticación. | proxy reparador |
INCAPSULA_ACCESS_DENIEDConfirmar mediante devolución realSuplemento de la guía de IA | Verificar las licencias, regiones y exportaciones de destino frente a los motivos reales de denegación; conservar evidencia para confirmar la compatibilidad del objetivo. | Confirmación manual |
Restricciones del destino y errores del servicio
| Código de error/fuente del documento | Sugerencias para solucionar problemas | Siguiente paso |
|---|---|---|
FORBIDDENTodas las versionesdocumento de respuesta | Primero verifique los permisos de destino, el estado de inicio de sesión y el cuerpo de la respuesta; Solo considere V2 si hay un mensaje de desafío claro y no trate todos los 403 como validación. | Confirmación manual |
ACCESS_DENIEDTodas las versionesdocumento de respuesta | Verifique las regiones permitidas, los permisos de cuenta y la reputación de exportación del objetivo, y conserve evidencia específica de denegación de acceso. | Confirmación manual |
TOO_MANY_REQUESTSTodas las versionesdocumento de respuesta | Primero reduzca la concurrencia y cumpla con el reintento posterior efectivo, verifique las cuotas de sitios y cuentas, y no dependa del cambio de IP para manejar las limitaciones actuales de forma predeterminada. | Retrocede y espera |
BAD_GATEWAYTodas las versionesdocumento de respuesta | Distinga entre proxies, puertas de enlace y orígenes de destino, y registre el tiempo de falla y la identificación de la solicitud; los fallos temporales se pueden retroceder y volver a intentar de forma segura. | Reintentos limitados |
SERVICE_UNAVAILABLETodas las versionesdocumento de respuesta | Compruebe si el destino o la puerta de enlace no está disponible temporalmente; reintento de control según la fecha límite y retroalimentación después de un fallo continuo. | Reintentos limitados |
SOURCE_SERVER_ERRORTodas las versionesdocumento de respuesta | Verifique la respuesta de error del sitio de origen y no modifique repetidamente parámetros irrelevantes; conservar el estado, la hora y el ID de la solicitud. | Reintentos limitados |
INTERNAL_ERRORTodas las versionesdocumento de respuesta | Conservar el ID de solicitud, la hora y la respuesta de desensibilización devueltas por Scrapingbypass API; Si continúa ocurriendo, entréguelo al soporte técnico. | soporte de retroalimentación |
GATEWAY_TIMEOUTConfirmar mediante devolución realSuplemento de la guía de IA | Localice si se trata de la puerta de enlace local, el proxy o el flujo ascendente, espere el tiempo de espera y luego intente nuevamente para detectar fallas temporales seguras y reproducibles. | Reintentos limitados |
Fuente:datos de respuesta、Diagnóstico de fallas de acceso de IA. Los errores desconocidos conservan sus valores originales y no se clasifican de manera uniforme como "Cambiar IP".
Mantenga la evidencia primeroDecide si intentarlo de nuevo
01. ¿Hay una respuesta HTTP?
Si no hay respuesta, primero verifique el entorno operativo, DNS, red, certificado y tiempo de espera del cliente. No invente códigos de error del servidor.
02. Leer dos niveles de resultados
x-cb-status: ok significa que la solicitud API se procesó correctamente; aún se deben verificar el estado de destino, el tipo de contenido y el contenido comercial.
03. Mantener campos de error
API Error JSON utiliza identificación, código y mensaje. SDK puede generar una excepción; es necesario leer la respuesta real.
04. Reintentar solo solicitudes que sean seguras de reproducir
Se detiene ante errores de configuración, saldo insuficiente y falta de permisos explícitos. Retraso limitado por fallas temporales; las operaciones con efectos secundarios confirman primero la idempotencia o el último resultado de la ejecución.
estructura de respuesta de error
{
"id": "<request-id>",
"code": "PARAMS_ERROR",
"message": "<error-message>"
}Los valores de los campos son de referencia; mantenga la respuesta real al solucionar problemas y no utilice ejemplos para cubrir los errores originales.
| Situación observada | Priorizar el juicio |
|---|---|
| 200/HTML | Podría ser contenido de destino, podría ser una página de inicio de sesión o una página de verificación; Verifique primero los campos comerciales. |
| 403 | Combine encabezados y cuerpo de respuesta para distinguir desafíos, permisos de cuenta y restricciones regionales. |
| 429 | Verifique primero la limitación actual y Reintentar después para reducir la simultaneidad. |
| 5xx | Diferenciar entre puerta de enlace local, proxy, origen de destino y errores devueltos por API. |

Versiones, proxies y SesionesNecesito comprobarlo juntos
01. Las cookies y las partes no se mezclan.
El cliente guarda el modo de cookie y envía cookies de verificación cifradas; El modo parcial está alojado en el servidor. Las sesiones de verificación de piezas se retienen durante 10 minutos, durante los cuales se pueden renovar las solicitudes exitosas, pero el período de validez del proxy no se extenderá.
02. Sesión de reconstrucción después de cambios de exportación
Mantenga la IP, la huella digital y el proxy consistentes durante el desafío; use una nueva sesión de Parte o Cookie después de cambiar la salida y no cambie de proxy simultáneamente en la misma partición.
03. Los bloqueos de sesión se ponen en cola primero
El primer desafío controla la simultaneidad por sesión. Espere o aísle tareas independientes cuando el bloqueo esté ocupado, e ignorar el bloqueo y forzar no se utilizan de forma predeterminada para eludir las restricciones de la sesión.
Verificación de versión de interfaz, proxy y tiempo de espera
| versión | Solicitudes y sesiones | x-cb-timeout |
|---|---|---|
| V1 | Viene con un proxy dinámico por defecto; cada solicitud es apátrida. x-cb-proxy se puede configurar según sea necesario. | Por defecto 30 segundos; 5–3600 segundos para Go V1. Los valores ilegales pueden ignorarse. |
| V2 | x-cb-version: 2; Se debe proporcionar un proxy fijo o urgente, seleccione el modo Cookie o Parte. | El valor predeterminado es 15 segundos; el Python V2 actual es de 5 a 360 segundos y los valores ilegales devuelven PARAMS_ERROR. |
| V2s | x-cb-version: 2s; sigue los requisitos de sesión y proxy V2, admite la transmisión de respuesta HTTP. | Por defecto 30 segundos; rango de 5 a 3600 segundos. Los clientes aún necesitan configurar su propio presupuesto de espera. |
Configuración de solicitud confusa
| Configuración | Cosas para comprobar |
|---|---|
| URL y x-cb-host | API La URL conserva la ruta de destino y los parámetros de consulta; x-cb-host completa el nombre del host de destino y los puertos necesarios, pero no completa el protocolo ni la ruta. |
| x-cb-protocol | Establecido explícitamente en http cuando el destino es HTTP; El valor predeterminado es https si no está configurado. |
| x-cb-proxy | Esta es la salida cuando el servicio API accede al destino y no equivale a configurar un proxy para el cliente HTTP local. Consulta certificaciones, convenios, disponibilidad y estabilidad exportadora. |
| x-cb-part | Sólo V2/V2; El rango predeterminado del documento es un número entero del 0 al 998; el rango real está sujeto a limitaciones del servicio. Aislar particiones para diferentes tareas. |
| x-cb-sitekey | Turnstile debe contar con el marcador de posición [cf_token] o %5Bcf_token%5D; La consulta JS no requiere completar la clave del sitio. |
| x-cb-fp / x-cb-ua | Verifique la huella digital de la versión real con el comportamiento de UA. Actualmente, Python V2 ignora x-cb-ua y no une aleatoriamente los números de versión del navegador. |
| Redirecciones y opciones de configuración | Las redirecciones se manejan de forma predeterminada; consulte deshabilitar redireccionamiento si necesita verificar 3xx y Set-Cookie. wait-lock está en desuso, ignore-lock y force no se utilizan como parches predeterminados. |
| Tiempos de espera y reintentos | El x-cb-timeout válido tiene prioridad sobre el tiempo de espera prolongado. Los plazos del cliente, SDK, el proxy y las tareas se verifican por separado para evitar la superposición de múltiples capas de reintentos automáticos. |
Existen diferencias en las descripciones del protocolo proxy en la página de parámetros y en la página de respuesta, que deben verificarse según la versión utilizada y el mensaje real; Los campos completos, rangos disponibles y diferencias de implementación son los siguientesDocumentación de parámetros de solicitud más recienteprevalecerá.
V2s es una respuesta de transmisión, no una tarea oficial en segundo plano, una encuesta o una interfaz de devolución de llamada. Las descargas deben verificar el estado del destino, el tipo de contenido y la integridad; ni 200 ni la existencia del expediente son suficientes para demostrar el éxito.
Documentos y herramientas, encuentra la entrada por pregunta.
Introducción y capacidad de respuesta
- inicio rápido
V1/V2/V2, tipos de desafío y dos modos de sesión.
- Solicitar parámetros
Ruta de destino, encabezados de solicitud, huellas digitales, tiempos de espera y opciones de configuración.
- datos de respuesta
x-cb-status, error JSON y tabla de códigos de error oficiales.
- Consultar saldo de cuenta
POST + JSON Puntos de consulta o tráfico de proxy.
SDK y acceso a IA
- Python SDK
Session/SessionV2, llamada asincrónica y consulta de saldo.
- Node.js SDK
cb_version, identificación de errores y prioridad de la variable de entorno.
- Ir SDK
Funciones de Cliente, Parte/Cookie y proxy.
- Vibe Coding Guía
Entorno de ejecución, estratificación de errores, reintentos limitados y límites de tareas de IA.
Herramientas y coleccionistas
- API a la herramienta de proxy local
Verifique la dirección de escucha, la clave predeterminada y x-cb-proxy.
- Nginx configuración de reenvío
El servidor guarda la clave y verifica el Host, SNI y el alcance del acceso.
- Configuración del recopilador
Reutilizar herramientas de proxy locales; No copie x-cb-host en la captura de pantalla.
Límites de facturación, prueba y capacidad
- Consumo de puntos
Las solicitudes exitosas y los desafíos exitosos se facturan por separado.
- Obtener una prueba
Después del registro, comuníquese con el servicio de atención al cliente según el documento.
- Navegadores de huellas dactilares y bordes automatizados
El documento claramente no admite el uso directo en navegadores de huellas digitales, Selenium y Puppeteer.
- WebSocket Límite
La documentación actual no admite explícitamente ws/wss.
Diferencias de configuración de puntos, saldo y SDK
Primero distinga entre puntos API y tráfico proxy
Descripción del documento oficial: una solicitud exitosa consume 1 punto y cada desafío de verificación V2 exitoso consume 2 puntos adicionales; la verificación de varias etapas se factura por separado. Si la respuesta posterior después de un desafío exitoso es incorrecta, los puntos del desafío ya deducidos no se devolverán, pero los puntos de la solicitud no se deducirán por una respuesta fallida. SDK Seguir automáticamente respuestas de redireccionamiento también consume puntos.
La interfaz de la balanza es POST https://console.cloudbypass.com/api/v1/balance, utilizando el campo JSON apikey、email、type。points Puntos de control y tiempo de vencimiento,res / dat Consulta el tráfico residencial/sala de ordenadores, la unidad es bytes. La antigua consulta GET está en desuso y no incluye credenciales en la URL.
SDK tiene diferentes convenciones de variables de entorno: Python / Uso de la documentación de Go CB_APIKEY、CB_PROXY;Node.js lectura prioritaria CLOUDBYPASS_APIKEY、CLOUDBYPASS_PROXY, lee de nuevo cuando esté vacío CB_*. Las variables de la guía AI no aparecen automáticamente en todos los entornos SDK o MCP remotos.
Tanto la herramienta del proxy local como Nginx son métodos de acceso de reenvío; la clave se almacena en un entorno operativo confiable y es necesario controlar el alcance del monitoreo y los permisos de acceso. La documentación explícitamente no admite el uso directo en navegadores de huellas digitales, Selenium/Puppeteer, ni admite ws/wss para WebSocket, y no confunde las respuestas de transmisión de HTTP con estas capacidades.
Preguntas frecuentes y evidencia de comentarios
HTTP 200 significa que la misión fue exitosa?
No. Primero verifique x-cb-status, luego verifique el estado del HTTP de destino, el tipo de contenido y los campos comerciales. x-cb-status: ok significa que la solicitud Scrapingbypass API se procesó correctamente, pero no significa que se deban completar el inicio de sesión, la realización de pedidos o el guardado de archivos y otros servicios.
Cuando no se recibe respuesta, ¿qué código de error se debe verificar?
Cuando no hay respuesta HTTP, no se puede fabricar el código de error del servidor Scrapingbypass API. Primero verifique las dependencias locales, el entorno operativo, el DNS, la red, el certificado y el tiempo de espera del cliente; Después de recibir la respuesta, lea la identificación, el código y el mensaje reales.
¿Es necesario cambiar todos los 403 a V2?
El número 403 también puede provenir de una cuenta sin permisos, restricciones regionales o reglas comerciales de destino. Cuando V1 indique claramente CLOUDFLARE_PREMIUM o devuelva información solicitando V2, configure V2 y el proxy estable; Los errores de permisos normales no desaparecerán automáticamente debido a las versiones actualizadas.
DataDome ¿Necesito agregar un encabezado de solicitud especial?
La documentación de inicio rápido indica que V2 reconoce automáticamente el desafío DataDome sin la necesidad de un encabezado dedicado DataDome adicional. El x-cb-proxy fijo o fijo aún debe configurarse y utilizar cookies coincidentes o sesiones parciales; La compatibilidad de objetivos requiere una verificación real.
¿Por qué no se completa Turnstile después de completar la clave del sitio?
x-cb-sitekey también debe coincidir con [cf_token] o su marcador de posición codificado en URL en la URL, el encabezado de la solicitud o el cuerpo de la solicitud. Scrapingbypass API reemplaza el marcador de posición y reenvía la solicitud de destino, en lugar de entregar el token desnudo directamente al cliente como valor de retorno general.
¿Por qué las solicitudes fallidas siguen consumiendo puntos?
La documentación distingue entre puntos de solicitud y puntos de desafío: una solicitud exitosa consume 1 punto y V2 consume 2 puntos adicionales por cada desafío de verificación exitoso. Si la respuesta posterior es incorrecta después de que el desafío sea exitoso, los puntos de desafío deducidos no se devolverán, pero los puntos de solicitud no se deducirán por la respuesta fallida; La verificación de múltiples etapas se calcula por etapa.
¿Las V2 son iguales a la interfaz de tareas asincrónicas en segundo plano?
No. Las V2 transmiten respuestas HTTP y no proporcionan automáticamente tareas oficiales en segundo plano, sondeos ni servicios de devolución de llamadas. Las llamadas asincrónicas desde el cliente no significan crear tareas en el servidor, y las descargas aún deben verificar el contenido real y la integridad.
¿Debo enviar la clave API al informar un problema?
No es necesario. Simplemente proporcione la hora y la zona horaria, el ID de la solicitud, el objetivo de desensibilización, la versión, el código/mensaje, la región y el tipo de proxy y el registro del intento. No envíe la clave API, la contraseña de proxy, la cookie de inicio de sesión, el cuerpo completo de la solicitud ni los parámetros de consulta con el token.

Mantenga esta información cuando se comunique con el soporte
- Hora de ocurrencia y zona horaria, ID de solicitud
- Objetivo de desensibilización, versión API, estado HTTP
- x-cb-status, código original y mensaje insensibilizado
- Tipo de proxy, región, período de validez y modo de sesión
- Pasos probados y resultado final
No viene con claves, contraseñas de proxy, cookies de inicio de sesión ni parámetros de consulta confidenciales. Si no hay ningún ID de solicitud, especifíquelo verazmente y no genere un valor sustituto.
