> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/consultar-estado.md).

# Check Status (polling)

Query the status of a validation transaction until it reaches a terminal state. While the transaction has not finished, the response contains only the identifier and the status. When it reaches a terminal state with diagnosis, it also includes the [result response](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/respuesta-de-resultado.md) complete.

### Endpoint

```
GET /document/validate/{transactionId}
```

### Headers

| Name              | Type   | Required | Description                                                                                                                           |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | **Yes**  | Consumer Token in Bearer format `Bearer <token>` (see [Authentication](/docs.facephi-en/rest-api/midapi-v2/autenticacion.md)).        |
| **consumer-id**   | string | **Yes**  | Consumer identifier.                                                                                                                  |
| **operation-id**  | string | **Yes**  | Validation [operation](/docs.facephi-en/rest-api/midapi-v2/operations.md) identifier, the same one that was sent when it was started. |

### Path parameters

| Parameter       | Type   | Required | Description                                                   |
| --------------- | ------ | -------- | ------------------------------------------------------------- |
| `transactionId` | string | **Yes**  | Transaction identifier returned by `POST /document/validate`. |

### Responses

#### `200` Success (transaction in progress)

```json
{
  "transactionId": "1c7d...e9",
  "status": "IN_PROGRESS"
}
```

#### `200` Success (terminal transaction)

When the transaction reaches a terminal state with diagnosis (`COMPLETED`), the response also includes the full diagnosis. See [Result response](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/respuesta-de-resultado.md).

### Transaction states

| State         | Meaning                                                                        | Terminal? |
| ------------- | ------------------------------------------------------------------------------ | --------- |
| `PROCESSED`   | The transaction was created and accepted for processing.                       | No        |
| `ERROR`       | The transaction could not be created/started (failure in the initial request). | Yes       |
| `IN_PROGRESS` | Validation is in progress.                                                     | No        |
| `COMPLETED`   | A diagnosis is available (`APPROVED`, `DECLINED` or `DOUBTFUL`).               | Yes       |
| `FAILED`      | Unrecoverable failure during processing. Includes `failureReason`.             | Yes       |

{% hint style="info" %}
The terminal state `COMPLETED` is unique for any result with diagnosis. In the event of `ERROR` or `FAILED`, there will be no `diagnostic` or `OCR` in the response. The state `FAILED` does include `failureReason` and `timestamp`.
{% endhint %}

### failureReason

When `status = FAILED`, the field `failureReason` describes the cause of the failure with a **generic and stable**. These are the possible values:

| failureReason                             | Meaning / recommended action                                                                                                               |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `Validation could not be completed`       | Transient processing failure. It is safe to **retry** by starting a new transaction with the same assets; if it persists, contact support. |
| `Internal processing error`               | Unexpected error during processing. Retry later; if it persists, contact support.                                                          |
| `Asset not found in storage: <fileKey>`   | One of the referenced assets could not be resolved. Verify that the `fileKeys` exist and were uploaded correctly before retrying.          |
| `Invalid <front\|back\|face> asset token` | The specified asset is not a valid capture token. Capture/upload that asset again and restart the process.                                 |

{% hint style="info" %}
`failureReason` is deliberately **generic**: different internal causes (including analysis timeouts) are grouped into `Validation could not be completed`. The specific detail remains in the service's internal logs; if you need to diagnose a case, share it with support together with the `transactionId`.
{% endhint %}

### Other responses

| Code  | Description                                                                                                                                                                               |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | The header `operation-id` is missing or empty.                                                                                                                                            |
| `401` | Missing, invalid, or expired Token.                                                                                                                                                       |
| `403` | The consumer is not provisioned with the service `DOCUMENT_ANTIFRAUD`.                                                                                                                    |
| `404` | The transaction does not exist or belongs to another consumer.                                                                                                                            |
| `429` | The consumer has exceeded its request rate limit. The response includes `Retry-After` with the wait seconds, and `X-RateLimit-Limit` and `X-RateLimit-Burst` with the current thresholds. |
| `503` | The service persistence is temporarily unavailable.                                                                                                                                       |

The body of an error response has the form described in [MIDAPI v2](/docs.facephi-en/rest-api/midapi-v2.md#respuestas-de-error).

{% hint style="warning" %}
The `429` of this Endpoint is the rate limit, and it should be taken into account when choosing the polling cadence: polling every few milliseconds causes it. The recommended strategy, phased and with backoff, is in [Best practices](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/buenas-practicas.md).
{% endhint %}