> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/es/docs/error-codes

# Códigos de error

Consulta la documentación de la API de Códigos de error, con parámetros de solicitud, campos de respuesta, ejemplos de código y gestión de errores para integraciones con DomScan.

### Errores estructurados

Todos los errores de la API devuelven la misma estructura JSON: un objeto `error` con un `code` estable, un `message` legible, su `type` y su `status` HTTP, si es `retryable`, el `request_id` y una `docs_url`. El `request_id` siempre coincide con la cabecera de respuesta `X-Request-Id`, así que inclúyelo cuando contactes con soporte.

```json
{
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "Formato de dominio no válido",
    "suggestion": "Usa un dominio registrable, como example.com",
    "type": "validation_error",
    "status": 400,
    "retryable": false,
    "request_id": "m5x7k2p-a9f3",
    "docs_url": "https://domscan.net/docs/check-availability"
  }
}
```

### Campos de error

| Campo | Descripción |
| --- | --- |
| `code` | Código de error estable y legible por máquina. Los códigos nunca se renombran, así que puedes basar tu lógica en ellos sin riesgo. |
| `message` | Explicación legible del error. El texto puede cambiar, así que no lo analices en tu código. |
| `type` | Categoría general del error, como `validation_error`, `authentication_error` o `rate_limit_error`. |
| `status` | El código de estado HTTP, repetido en el cuerpo para registros y colas. |
| `retryable` | Indica si la misma solicitud puede tener éxito si la reintentas más tarde. |
| `request_id` | Identificador único de la solicitud. Coincide con la cabecera `X-Request-Id`. |
| `docs_url` | Enlace a la sección de la documentación que explica este error. |
| `suggestion` | Indicación opcional sobre cómo corregir la solicitud. |
| `details` | Contexto estructurado opcional, como los métodos permitidos o el parámetro no válido. |
| `retry_after` | Número opcional de segundos que debes esperar antes de reintentar. También se envía en la cabecera `Retry-After`. |

### Códigos de error habituales

Estos son los códigos que la mayoría de los clientes necesitan gestionar. Algunos endpoints devuelven códigos más específicos que siguen las mismas reglas; la lista completa con estado, tipo y comportamiento de reintento está en la especificación OpenAPI, en `x-domscan-error-codes`. `RATE_LIMIT_EXCEEDED` se sigue aceptando como alias de `RATE_LIMITED`.

| Código | Estado HTTP | Tipo | Reintentable | Descripción |
| --- | --- | --- | --- | --- |
| `BAD_REQUEST` | 400 | `validation_error` | No | Parámetros ausentes o no válidos |
| `MISSING_PARAMETER` | 400 | `validation_error` | No | Falta un parámetro obligatorio |
| `INVALID_PARAMETER` | 400 | `validation_error` | No | Un parámetro tiene un valor no válido |
| `INVALID_JSON` | 400 | `validation_error` | No | El cuerpo de la solicitud no es un JSON válido |
| `INVALID_DOMAIN` | 400 | `validation_error` | No | Formato de dominio no válido |
| `UNSUPPORTED_TLD` | 400 | `validation_error` | No | TLD no compatible |
| `SUBDOMAIN_NOT_SUPPORTED` | 400 | `validation_error` | No | Este endpoint acepta dominios registrables, no subdominios |
| `VALIDATION_ERROR` | 422 | `validation_error` | No | La solicitud está bien formada, pero no se puede procesar |
| `AUTH_REQUIRED` | 401 | `authentication_error` | No | No se proporcionó ninguna clave de API ni sesión |
| `INVALID_API_KEY` | 401 | `authentication_error` | No | La clave de API no es válida o ha sido revocada |
| `INSUFFICIENT_CREDITS` | 402 | `credits_error` | No | Tu cuenta no tiene créditos suficientes para esta solicitud |
| `FORBIDDEN` | 403 | `permission_error` | No | No tienes permiso para realizar esta acción |
| `NOT_FOUND` | 404 | `not_found_error` | No | El endpoint o el recurso no existe |
| `METHOD_NOT_ALLOWED` | 405 | `request_error` | No | El endpoint existe, pero no acepta este método HTTP. La cabecera `Allow` enumera los métodos compatibles. |
| `CONFLICT` | 409 | `conflict_error` | No | La solicitud entra en conflicto con el estado actual del recurso |
| `IDEMPOTENCY_CONFLICT` | 409 | `conflict_error` | No | La clave de idempotencia ya se usó con una solicitud diferente |
| `IDEMPOTENCY_KEY_REUSED` | 422 | `validation_error` | No | Esta `Idempotency-Key` ya se usó con una solicitud diferente en las últimas 24 horas. Usa una clave nueva para una solicitud nueva. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | `conflict_error` | Sí | Una solicitud con esta `Idempotency-Key` sigue en curso. Vuelve a intentarlo en un momento para recibir su respuesta almacenada. |
| `RATE_LIMITED` | 429 | `rate_limit_error` | Sí | Demasiadas solicitudes |
| `INTERNAL` | 500 | `api_error` | No | Error inesperado del servidor. Si persiste, contacta con soporte e indica el ID de la solicitud. |
| `UPSTREAM_ERROR` | 502 | `upstream_error` | Sí | Una fuente de origen devolvió una respuesta inutilizable |
| `UPSTREAM_UNAVAILABLE` | 503 | `upstream_error` | Sí | Una fuente de origen no está disponible temporalmente |
| `SERVICE_UNAVAILABLE` | 503 | `upstream_error` | Sí | El servicio no está disponible temporalmente |
| `TIMEOUT` | 504 | `timeout_error` | Sí | Una fuente de origen o un registro no respondió a tiempo |

### Pautas para reintentar

- Reintenta solo cuando `retryable` sea `true`. En los errores de validación, autenticación y permisos, corrige primero la solicitud.

- Cuando esté presente `retry_after` o la cabecera `Retry-After`, espera al menos esa cantidad de segundos antes del siguiente intento.

- En los demás casos, usa un retroceso exponencial con jitter, por ejemplo 1, 2, 4 y 8 segundos, y detente tras unos pocos intentos.

- Al crear lotes y trabajos, envía una cabecera `Idempotency-Key` para que una solicitud reintentada nunca cree un trabajo duplicado.

- En otras solicitudes POST que cobran créditos, una cabecera `Idempotency-Key` hace que un reintento devuelva la respuesta almacenada en lugar de volver a cobrar.

### Compatibilidad

Desde el 10 de octubre de 2026, todos los endpoints usan este formato. Los campos que algunos endpoints ya devolvían, como `credits_remaining`, `purchase_url`, `login_url`, `success` o `meta`, se mantienen durante un periodo de compatibilidad, de modo que las integraciones existentes siguen funcionando. En el código nuevo, lee los detalles del error en el objeto `error`.