> ## Documentation Index
> Fetch the complete documentation index at: https://alphacastio.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# API Error Codes and Troubleshooting
> Reference for every HTTP error code returned by the Alphacast API — 400, 401, 402, 403, 404, 409, 429, 500, 503, 504 — with causes, example responses, and fixes.
When an API request fails, Alphacast returns a standard HTTP error status code and, where possible, a JSON body that describes what went wrong. This page covers every error code you may encounter, what typically causes it, and how to fix it.
## Error response format
Most error responses follow this shape:
```json theme={null}
{
"error": "Description of what went wrong"
}
```
Some errors — particularly `401` and `500` — may return an empty body or a plain-text message depending on where in the request lifecycle the failure occurs.
## Error codes
### 400 Bad Request
Your request was understood but contained invalid or missing data.
```json theme={null}
{
"error": "repositoryId is required"
}
```
**Common causes:**
* A required field is missing from the request body. For example, creating a dataset without providing `repositoryId`.
* The request body is malformed JSON. Verify that your payload is valid and that you have set `Content-Type: application/json`.
* An OData `$filter` expression references a column that does not exist in the dataset. The error message will look like:
```json theme={null}
{
"error": "Filter contains invalid column(s): region"
}
```
Check the column names in the dataset exactly as they appear — column names are case-sensitive.
***
### 401 Unauthorized
Your request did not include valid credentials, or no credentials were provided at all.
**Common causes and fixes:**
* **Missing API key** — Include your API key via HTTP Basic Auth or the `?apiKey=` query parameter. See the [API overview](/api/overview) for the correct format.
* **Key in the wrong field** — When using Basic Auth, the API key must be the **username**, not the password. A common mistake is reversing these:
```bash theme={null}
# Correct
curl -u YOUR_API_KEY: https://api.alphacast.io/repositories
# Incorrect — key is in the password field
curl -u :YOUR_API_KEY https://api.alphacast.io/repositories
```
* **Invalid or revoked key** — Verify your key in Alphacast account settings. If you recently regenerated it, update any integrations that use the old key.
***
### 402 Payment Required
The action you attempted requires a higher membership tier than your current plan provides.
```json theme={null}
{
"error": "This action requires a membership upgrade."
}
```
**Common causes:**
* Creating an additional private repository beyond your plan's limit.
* Fetching data from a paid-tier provider while on a free plan.
* Downloading data that exceeds your plan's monthly export quota.
**Fix:** upgrade your Alphacast subscription, or remove an existing resource to free up quota.
***
### 403 Forbidden
Your credentials are valid, but you do not have permission to perform this action on the requested resource.
**Common causes:**
* You are attempting to write to (or delete from) a repository where you only have **Read** permission. Contact the repository owner to request Write access.
* You are trying to access a private resource that belongs to another account.
***
### 404 Not Found
The resource you requested does not exist.
```json theme={null}
{
"error": "Not found"
}
```
**Common causes:**
* The dataset or repository ID in the URL is wrong. Double-check the ID in the Alphacast UI or via a `GET /datasets` list request.
* The resource was deleted after you last retrieved its ID.
***
### 409 Conflict
The request could not be completed because it conflicts with an existing resource.
```json theme={null}
{
"error": "A dataset named 'CPI Monthly' already exists in repository 45."
}
```
**Common causes:**
* Creating a dataset with a name that already exists in the same repository.
* Uploading data with a column manifest that conflicts with the dataset's existing column types.
* Saving a provider API key while another concurrent request is updating the same key.
**Fix:** rename the resource, delete the existing one, or retry once the conflicting request completes.
***
### 429 Too Many Requests
You hit a rate limit. Alphacast does not enforce a global API limit, but the provider connectors honor each upstream's limits on your behalf — if FRED, BLS, or any other source caps requests per minute or per day, Alphacast surfaces that as a `429`.
```json theme={null}
{
"error": "Upstream provider rate limit exceeded for fred. Try again in a few seconds."
}
```
**Common causes and fixes:**
* The upstream provider's rate limit was reached. Save your own API key with `PUT /user-keys/{slug}` to raise the limit (especially for FRED and BLS, which are far more generous with an authenticated key).
* Many concurrent series fetches against the same provider. Serialize the calls or add backoff.
***
### 500 Internal Server Error
An unexpected error occurred on the server. This is not caused by your request.
**What to do:**
* Wait a moment and retry the request — transient errors often resolve on their own.
* If the error persists, note the endpoint, request body, and approximate time of the failure, then contact Alphacast support.
For errors that originate inside a provider connector, the response message is **sanitized** — it does not include upstream URLs, internal tokens, or stack traces. The unredacted detail is kept in Alphacast's server logs, so include the endpoint and timestamp when filing a support request.
A `500` response is never caused by invalid input in your request. If you see one consistently for the same request, it is a server-side issue worth reporting.
***
### 503 Service Unavailable
The API is temporarily unable to handle the request, typically because of a deploy in progress or an overloaded backend dependency.
**What to do:** retry with exponential backoff. Most `503` responses clear within a few seconds.
***
### 504 Gateway Timeout
The request took longer than the gateway timeout to complete. Most often this happens on long-running operations such as fetching the full history of a large provider series, or downloading a very wide dataset.
**What to do:**
* Narrow the response: pass `$top`, `$last`, or `$filter` to `GET /datasets/{id}/data`, or restrict the date range when fetching provider series.
* Retry the same request after a short delay — transient timeouts often resolve.
## Debugging checklist
If you are not sure which error applies to your situation, work through this checklist:
1. **Check the status code** — The HTTP status in the response headers is always the authoritative signal.
2. **Read the error message** — The `error` field in the JSON body usually describes the problem specifically.
3. **Confirm authentication** — Re-run the request with `curl -v` to inspect the `Authorization` header being sent.
4. **Validate your JSON** — Paste your request body into a JSON validator to catch syntax errors before sending.
5. **Verify resource IDs** — Fetch the parent resource (e.g., `GET /repositories`) to confirm the IDs you are using still exist.
6. **Check column names in filters** — If using `$filter`, list the dataset columns first with `GET /datasets/{id}/columns` to confirm exact names.