> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ebrc.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error handling for the eBRC API: the error body shape, every HTTP status code, common validation messages with exact text, and DGFT credential error codes.

Successful responses are wrapped in the standard envelope documented in the [API Reference introduction](/api-reference/introduction#response-envelope). Errors are not wrapped; they use the shape below.

## Error body

```json theme={"dark"}
{
  "statusCode": 400,
  "timestamp": "2026-07-22T10:15:04.874Z",
  "path": "/api/v1/genebrc/push-irm",
  "method": "POST",
  "message": "Validation failed",
  "errors": [
    "uploadType: uploadType must be a string",
    "ebrcBulkGenDtos.0.serialNo: serialNo must be a number conforming to the specified constraints"
  ],
  "error": "Bad Request",
  "requestId": "b3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}
```

| Field                    | Always present | Meaning                                                     |
| ------------------------ | -------------- | ----------------------------------------------------------- |
| `statusCode`             | Yes            | HTTP status code                                            |
| `timestamp`              | Yes            | When the error occurred (ISO 8601)                          |
| `path`                   | Yes            | The request path                                            |
| `method`                 | Yes            | The HTTP method                                             |
| `message`                | Yes            | Human-readable summary. Do not branch on it                 |
| `errors`                 | No             | Per-field validation messages                               |
| `error`                  | No             | Error type, e.g. `Bad Request`                              |
| `errorCode`              | No             | Stable machine-readable code. Branch on this                |
| `requiresPasswordUpdate` | No             | Whether re-submitting DGFT credentials would resolve it     |
| `causes`                 | No             | Human-readable probable causes, safe to display             |
| `requestId`              | No             | Quote this to [amin@eximfiles.io](mailto:amin@eximfiles.io) |

## HTTP status codes

| Code | Meaning                                                             |
| :--: | ------------------------------------------------------------------- |
|  200 | Request successful                                                  |
|  201 | Resource created (customer create, credential validation)           |
|  400 | Invalid request parameters or failed validation                     |
|  401 | Missing or invalid API key                                          |
|  403 | Key valid but not permitted, or contract signing incomplete         |
|  404 | Resource not found                                                  |
|  409 | DGFT credential conflict, see the credential error codes below      |
|  422 | DGFT configuration issue, for example no credentials on file        |
|  429 | Rate limit exceeded, see [rate limits](/authentication#rate-limits) |
|  500 | Internal server error                                               |
|  502 | The government system was unreachable, retry after a short delay    |
|  503 | Service temporarily unavailable, retry after a short delay          |

## Common validation errors

Validation failures return **400** with `message: "Validation failed"` and an `errors` array. Each entry is `field: constraint`. The exact messages you will see most often:

| `errors` entry                                                                                      | What it means                                                                                 |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `uploadType: uploadType must be a string`                                                           | The message-level `uploadType` is a string code, e.g. `"101"`                                 |
| `ebrcBulkGenDtos.0.uploadType: uploadType must be a number conforming to the specified constraints` | The item-level `uploadType` is a number, e.g. `101`                                           |
| `isGstAvail: isGstAvail must be one of the following values: Y, N`                                  | Only `Y` or `N` is accepted                                                                   |
| `gstinInvoiceNumber: gstinInvoiceNumber should not be empty`                                        | Mandatory because `isGstAvail` is `Y`                                                         |
| `gstinInvoiceNumber: gstinInvoiceNumber must be empty`                                              | Must be `null` because `isGstAvail` is `N`                                                    |
| `email: email must be an email`                                                                     | Customer email failed format validation                                                       |
| `property x should not exist`                                                                       | Unknown fields are rejected, check spelling against the [field reference](/annexure/push-irm) |

Bulk Excel uploads return row-level errors instead, each with `row`, `field` and `message`. See [Bulk Upload via Excel](/api-reference/genebrc/bulk-upload).

## DGFT credential error codes

Endpoints that operate on a customer's DGFT connection return a structured error when that connection fails. Branch on `errorCode`, never on `message`:

| `errorCode`                | HTTP | `requiresPasswordUpdate` | What to do                                                                      |
| -------------------------- | :--: | :----------------------: | ------------------------------------------------------------------------------- |
| `DGFT_CREDENTIALS_INVALID` |  409 |          `true`          | [Update the stored DGFT password](/api-reference/customer/validate), then retry |
| `DGFT_ACCOUNT_LOCKED`      |  409 |          `true`          | Reset the password on the DGFT portal, update it here, then retry               |
| `DGFT_CREDENTIALS_MISSING` |  422 |          `true`          | [Link the customer's DGFT account](/api-reference/customer/validate) first      |
| `EBRC_NOT_FOUND`           |  404 |          `false`         | Certificate not on the portal yet, retry later                                  |
| `DGFT_PORTAL_UNAVAILABLE`  |  502 |          `false`         | Retry after a short delay                                                       |

## Related

* [Authentication](/authentication) for auth failures and rate limits.
* [Download eBRC PDF](/api-reference/genebrc/download) shows credential error recovery end to end.
* [Push IRM Request Fields](/annexure/push-irm) for every field's format and constraints.