# Appendix A: Error Code Reference

### 4xx Client Errors

#### 400 Bad Request

| Error Code                           | Description                                                                                    |
| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `CLIENT_ID_INVALID`                  | Invalid or unknown client identifier.                                                          |
| `REDIRECT_URI_INVALID`               | The redirect URI does not match any of the pre-registered URIs for this client.                |
| `BALANCE_INVALID`                    | Your account balance is insufficient to complete this transaction. Please add funds and retry. |
| `PAYMENT_EXCEPTION`                  | We were unable to process your payment. Please verify your payment method and try again.       |
| `INSUFFICIENT_USER_BALANCE`          | Insufficient user balance.                                                                     |
| `ATTACHMENT_SIZE_EXCEEDED_500MB`     | The attached file size exceeds the 500 MB limit.                                               |
| `PDF_ATTACHMENT_PAGES_EXCEEDED`      | The PDF file exceeds the maximum allowed limit of 700 pages.                                   |
| `REPEAT_RECORDS`                     | A record with identical data already exists. Duplicate submission is not allowed.              |
| `INCORRECT_ID`                       | The provided identifier format is incorrect or malformed.                                      |
| `ATTACHMENT_ADDRESS_DOWNLOAD_FAILED` | Failed to download the file from the provided attachment address.                              |

#### 401 Unauthorized

| Error Code                  | Description                                                                       |
| --------------------------- | --------------------------------------------------------------------------------- |
| `API_KEY_INVALID`           | Invalid or malformed API key provided.                                            |
| `TOKEN_INVALID`             | The access token provided is invalid, expired, or revoked.                        |
| `MISSING_AUTH_INFO`         | Required authentication information is missing. Please include valid credentials. |
| `USERNAME_PASSWORD_INVALID` | Authentication failed due to incorrect username or password.                      |
| `REFRESH_TOKEN_INVALID`     | The refresh token provided is invalid or has expired.                             |

#### 404 Not Found

| Error Code       | Description                                          |
| ---------------- | ---------------------------------------------------- |
| `USER_NOT_FOUND` | No user account found with the provided information. |

***

### 5xx Server Errors

#### 500 Internal Server Error

| Error Code               | Description                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| `INTERNAL_SERVER_ERROR`  | An unexpected internal server error occurred. Our engineering team has been notified.                     |
| `COMPANY_NOT_FOUND`      | No official filings found for the company \[Company name].                                                |
| `COMPANY_LIMIT_EXCEEDED` | The request contains too many companies. Please limit your query to a maximum of 5 companies per request. |
| `QUERY_TOO_BROAD`        | Your search query is too broad. Please provide a more specific research question or criteria.             |
| `TIMEOUT`                | The server is taking longer than expected to process your request. Please try again later.                |
| `NO_DATA_IN_PERIOD`      | No filings were found for \[Company] within the past 12 months.                                           |
| `TASKID_NOT_FOUND`       | No task or associated data found for the ID \[Task ID].                                                   |
| `PROCESSING_ERROR`       | An error occurred while processing your request.                                                          |

#### 503 Service Unavailable

| Error Code                   | Description                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------- |
| `PDF_CORRUPTED_PARSE_FAILED` | The provided PDF file appears to be corrupted and cannot be parsed.          |
| `PDF_PARSE_FAILED`           | The server failed to parse the PDF file due to an internal processing error. |

#### 504 Gateway Timeout

| Error Code          | Description                                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `PDF_PARSE_TIMEOUT` | The request to parse the PDF file has timed out. Please try again with a smaller file or different document. |

***

### Error Response Format Example

```json
{
  "error": {
    "code": "API_KEY_INVALID",
    "status": 401,
    "message": "Invalid or malformed API key provided."
  }
}
```

***

### Handling Recommendations

* **4xx Errors**: Check request parameters, authentication credentials, and permission configurations
* **5xx Errors**: Retry later; contact technical support if the issue persists
* **Timeout Errors**: Consider reducing request payload or processing in batches