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.

Lupa para examinar los campos de excepción y solicitar registros en la respuesta API

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.

Parámetros y cuenta

Parámetros y cuentas: código, versiones aplicables y sugerencias para la resolución de problemas
Código de error/fuente del documentoSugerencias para solucionar problemasSiguiente 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

Proxies, redes y certificados: código, versiones aplicables y sugerencias para la solución de problemas
Código de error/fuente del documentoSugerencias para solucionar problemasSiguiente 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

Sesiones y desafíos de verificación: código, versiones aplicables y sugerencias para la solución de problemas
Código de error/fuente del documentoSugerencias para solucionar problemasSiguiente 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

Limitaciones de destino y excepciones de servicio: código, versiones aplicables y sugerencias para la solución de problemas
Código de error/fuente del documentoSugerencias para solucionar problemasSiguiente 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.

El fenómeno HTTP no es igual al código de error del servicio Scrapingbypass API
Situación observadaPriorizar el juicio
200/HTMLPodrí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.
403Combine encabezados y cuerpo de respuesta para distinguir desafíos, permisos de cuenta y restricciones regionales.
429Verifique primero la limitación actual y Reintentar después para reducir la simultaneidad.
5xxDiferenciar entre puerta de enlace local, proxy, origen de destino y errores devueltos por API.

Ver convención de respuesta completa

PRT00023 Relación de configuración entre los parámetros de solicitud PRT, salida de proxy y sesión estable

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ónSolicitudes y sesionesx-cb-timeout
V1Viene 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.
V2x-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.
V2sx-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ónCosas para comprobar
URL y x-cb-hostAPI 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-protocolEstablecido explícitamente en http cuando el destino es HTTP; El valor predeterminado es https si no está configurado.
x-cb-proxyEsta 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-partSó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-sitekeyTurnstile 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-uaVerifique 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ónLas 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 reintentosEl 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

SDK y acceso a IA

Herramientas y coleccionistas

Límites de facturación, prueba y capacidad

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 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.

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.

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.

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.

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.

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.

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.

Organice el tiempo de ocurrencia, la respuesta de error y los registros de diagnóstico y envíelos al soporte técnico.

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.

Escenarios de acceso y uso de IA

Oferta de prueba
+ 200 API créditos
+ Proxies rotativos
Solicitar ahora ›