Skip to main content
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: 
{
  "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. 
{
  "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: 
    {
  "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 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: 
    # 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. 
{
  "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. 
{
  "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. 
{
  "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. 
{
  "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.