# Errores y códigos de estado

Encuentra la causa de una solicitud fallida y decide si arreglarla, esperar o volver a entrar.

Referencia canónica: https://flashdata.dev/es/docs/errors
Revisado: 2026-11-04 por FlashData

<a id="status-codes"></a>

## Códigos de estado HTTP

Comience con el estado HTTP, luego lea el código de error y el mensaje para la causa específica.

| Situación | Significado | Qué hacer |
| --- | --- | --- |
| 400 | Solicitud inválida | Arreglar la fuente, campos requeridos, tipos de parámetro o encabezados de respuesta antes de reintentar. |
| 401 | Falló la autenticación | Compruebe X-API-Key. Reemplazar una llave caducada o revocada; reiniciar la misma tecla no ayudará. |
| 402 | Créditos insuficientes | Verifique el saldo de la cuenta. Agregue créditos o deje que el propietario de la cuenta resuelva el acceso antes de enviar de nuevo. |
| 403 | Acceso denegado | Compruebe los permisos de origen de la clave y el estado de cuenta o suscripción. |
| 404 | No se encontró | Consulta el URL, trabajo ID y cuenta. Trabajos fuera de tu cuenta o fuentes permitidas también pueden devolver 404. |
| 406 | Tipo de respuesta no aceptable | Use Accept: application/json o text/plain. Seleccione Markdown con X-Respond-With: marcador. |
| 409 | Resultado no listo / conflicto | En un resultado leído, encuesta el trabajo existente hasta que se complete. Para otros puntos finales, resolver el conflicto descrito en el cuerpo. |
| 410 | Resultado vencido | Usar una copia guardada. Reiniciar el resultado URL no puede restaurar un resultado vencido. |
| 422 | Entrada inválida / trabajo fallido | Arreglar los campos reportados. En un resultado leído, inspeccione job.error: un trabajo fallido no tiene resultado exitoso para buscar. |
| 429 | Límite alcanzado | Espere a Retry-After o retry_after. Reduzca la tasa de solicitud; para una cola pendiente completa, espere a que los trabajos existentes terminen. |
| 500 / 502 / 503 / 504 | Insuficiencia de servicio o aguas arriba | Retry lee con el backoff atado. Para un POST o el tiempo de envío, compruebe si el trabajo fue aceptado antes de enviarlo de nuevo. |

- [Compruebe las teclas API](https://flashdata.dev/app/api-keys)
- [Créditos y precios](https://flashdata.dev/es/docs/guides/credits-and-billing/reference.md)
- [Límites de solicitudes](https://flashdata.dev/es/docs/guides/usage-and-limits/reference.md)

<a id="response"></a>

## Lea una respuesta de error

Los errores de API usan JSON, incluso cuando usted solicita un texto plano. El cuerpo difiere por punto final. Rama en el estado y código HTTP cuando está presente; utilice el mensaje o el detalle para explicar el problema.

### Query API

Los errores de consulta suelen incluir errores y mensajes; el código es opcional. Los errores de autenticación pueden usar el éxito: falso en lugar de error: verdadero.

#### 400 · application/json

```json
{
  "error": true,
  "code": "unsupported_representation",
  "message": "X-Respond-With supports markdown. Omit the header for the original result fields."
}
```


### API de gestión

Las respuestas de error de V2 utilizan application/problem+json. Conserva requestId para soporte. Los errores de validación también pueden incluir fieldErrors con field, code y message.

#### 401 · application/problem+json

```json
{
  "type": "https://api.flashdata.dev/problems/invalid_api_key",
  "title": "Invalid API Key",
  "status": 401,
  "code": "invalid_api_key",
  "requestId": "example-request-id",
  "detail": "The API Key is invalid or unavailable."
}
```



<a id="diagnostics"></a>

## Estado de inspección, encabezados y cuerpo

Utilice curl --include para ver los tres. Este ejemplo comprueba su clave con una cuenta gratuita leída; no presenta una consulta. Establecer FLASHDATA_API_KEY en su entorno primero.

### Inspeccionar una respuesta · cURL / Bash

```bash
curl --include --silent --show-error --max-time 20 \
  'https://api.flashdata.dev/v2/api-access/identity' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Accept: application/json'
```

- [Configuración de autenticación](https://flashdata.dev/es/docs/guides/headers-and-authentication/reference.md)
- [Solución de problemas por síntoma](https://flashdata.dev/es/docs/guides/troubleshooting/reference.md)

<a id="retries"></a>

## Cuándo volver a entrar

Un POST repetido puede crear otra consulta facturable. Un tiempo de red no prueba que la primera solicitud fue rechazada. Guardar el trabajo ID tan pronto como lo recibas.

| Situación | Siguiente acción |
| --- | --- |
| Entrada inválida, clave, permiso o saldo | Parar. Arreglar el estado de solicitud o cuenta antes de reintentar; no aflore en estos errores. |
| 429 con una pista de espera | Honor Retry-After (segundos o HTTP date), o el valor JSON retry_after en segundos. Si ambos están presentes, use el retraso más largo. |
| Solicitud de información: 429 / error temporal 5xx / red | Retrocede el mismo GET. Sin una pista de espera, utilice demoras crecientes con jitter, un recuento máximo de intento y un límite de tiempo. |
| POST timeout o ambiguo 5xx | Mantenga el trabajo existente ID y compruebe su estado. Si no se recibió ID, inspeccione la historia del trabajo antes de decidir someterse de nuevo. |

- [Historia laboral](https://flashdata.dev/app/jobs)
- [Recuperar una tarea de agente](https://flashdata.dev/es/docs/guides/agent-recovery/reference.md)

<a id="job-status"></a>

## Revisar un trabajo de fondo

HTTP 200 desde el punto final del estado significa que la lectura tuvo éxito. Chequee job.status para saber si la tarea tuvo éxito. Establecer JOB_ID a su trabajo existente; este comando no presenta un reemplazo.

| job.status | Qué hacer |
| --- | --- |
| pending / processing | Espera, luego encuesta el mismo trabajo. Un resultado lee devuelve 409 hasta la finalización. |
| completed | Recuperar y guardar el resultado. Los resultados originales JSON devuelven una red de almacenamiento 302; los resultados formateados devuelven un cuerpo directamente. |
| failed | Deja de votar e inspeccionar job.error. El punto final del resultado devuelve 422 con el código result_not_ready para un trabajo fallido. |

### Leer el estado de trabajo · cURL / Bash

```bash
curl --fail-with-body --silent --show-error --max-time 30 \
  "https://api.flashdata.dev/v2/jobs/${JOB_ID:?Set JOB_ID}" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Accept: application/json'
```

- [Estado de comprobación · Python y cURL](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md#status)
- [Recuperar los resultados](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md#results)
- [Progresos en el trabajo de Bulk](https://flashdata.dev/es/docs/reference/bulk-processing/reference.md#getBulkJob)

<a id="response-formats"></a>

## Errores de formato de respuesta

| Estado / código | Arreglos |
| --- | --- |
| 400 · unsupported_representation | Establecer X-Respond-With para marcar, o eliminar el encabezado. |
| 406 · not_acceptable | Establece Accept en application/json o text/plain. Si especificas un juego de caracteres, usa UTF-8. |

- [Ejemplos de formularios de solicitud y respuesta](https://flashdata.dev/es/docs/guides/response-formats/reference.md)

<a id="support"></a>

## Obtener ayuda con una solicitud

Enviar el punto final, UTC timestamp, HTTP status, código de error y solicitud o trabajo ID. Eliminar las teclas API, fichas y firmó URLs del informe.

- [Contactar con soporte](https://flashdata.dev/es/contact)
