Requests & Responses

Content Type

Except for the OAuth token creation endpoint, our API only supports application/json content-type. In the future, as a defensive approach to avoid unwanted broken queries, please always attach a Content-Type header to your API requests.

Versioning

The API is versioned using a version tag in the URL (e.g, /v1.0/). Breaking changes are deployed with an incremented API version. Older versions may be marked deprecated and be shutdown.

HTTP Statuses

Spark uses conventional HTTP response codes to indicate the success or failure of an API request.

In general, if the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered.

Return codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed.

If you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently.

Here is a list of supported codes:

• 200: Successful Operation
• 201: Entity Created
• 400: Bad Request Exception / Limit Exceeded Exception
• 401: Unauthorized
• 403: Forbidden
• 422: Validation Error
• 429: Too Many Requests Exception
• 500: Internal Server Error
• 503: Maintenance Mode

Responses and Data Format

A response body will be sent back in the form of a JSON object or an array of JSON objects under the data key for any request. Our API supports JSON format, and CSV for some endpoints.

In the event of a problem, the body of the response will usually contain additional information about the problem that was encountered under the errors key.

Rate Limits

Spark Commodities limits the number of REST API requests that you can make within a specific amount of time. This limit helps prevent abuse and denial-of-service attacks, and ensures that the API remains available for all users.

You can use an access token to make API requests on your behalf. All of these requests count towards your personal rate limit of 600 requests per hour.