Errors
The Marketstack API uses standard HTTP status codes to indicate whether a request was successful or failed. When an error occurs, the API returns a JSON response containing details that help identify and resolve the issue.
Understanding these responses allows developers to troubleshoot problems efficiently and adjust their requests accordingly.
HTTP Status Codes
The following table describes common HTTP status codes returned by the Marketstack API and their meanings.
| Code | Description |
|---|---|
| 200 OK | The request was processed successfully and valid data was returned. |
| 400 Bad Request | The request is malformed or contains invalid or missing parameters. Review query parameters and formatting. |
| 401 Unauthorized | The access key is missing, invalid, or not properly included in the request. |
| 403 Forbidden | The request is valid but not permitted under the current subscription plan or account permissions. |
| 404 Not Found | The requested endpoint or resource could not be found. |
| 429 Too Many Requests | The allowed request limit for the current subscription period has been exceeded. |
| 500 Internal Server Error | 500 Internal Server Error |
Error Response Format
When a request fails, the API returns an error response in JSON format that provides additional details about the problem. This response typically includes:
- An error message describing what went wrong
- An error code that categorizes the type of failure
These details help determine whether the issue is related to authentication, request structure, usage limits, or server-side conditions.
Common Error Scenarios
The following are common situations in which errors may occur when working with the Marketstack API:
- An access key is missing, incorrect, or expired
- The monthly request limit for the free plan has been exceeded
- Query parameters are misspelled, unsupported, or incorrectly formatted
- Data is requested that is not available under the current subscription tier
- An invalid symbol or exchange code is provided
Recognizing these scenarios can help reduce failed requests and improve integration reliability.
Troubleshooting Tips
If an error occurs, consider the following steps before retrying the request:
- Confirm that the access key is valid and included correctly in the request
- Double-check parameter names, values, and formatting
- Ensure the request does not exceed plan limitations such as monthly request quotas
- Review the HTTP status code and error message returned in the response
- Retry the request after some time if the issue appears to be temporary
These steps can help quickly identify and resolve most common API issues.