Requests & Responses

This guide explains how to format requests to the Spark API and what to expect in responses.

Content Type

All Spark API endpoints use application/json format, with the exception of the OAuth token endpoint.

Best Practice: Always include the Content-Type header in your requests to ensure proper handling:

Content-Type: application/json

Future-Proofing

Including the Content-Type header helps prevent issues as the API evolves and ensures your requests are processed correctly.

API Versioning

The API uses URL-based versioning with a version tag in the path:

https://api.sparkcommodities.com/v1.0/endpoint

Important:

• Breaking changes are released as new API versions (e.g., v2.0)
• Older versions may be deprecated with advance notice
• You'll be notified before any version is shut down
• Beta versions (/beta/ in the URL) are subject to change at any moment without notice

Stay Updated

Always use the latest API version when possible to access new features and improvements.

HTTP Status Codes

The Spark API uses standard HTTP status codes to indicate request outcomes:

Success Codes (2xx)

Code	Meaning	Description
200	OK	Request succeeded, data returned
201	Created	New resource successfully created

Client Error Codes (4xx)

Code	Meaning	Description
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Valid authentication but insufficient permissions
422	Validation Error	Request data failed validation rules
429	Too Many Requests	Rate limit exceeded

Server Error Codes (5xx)

Code	Meaning	Description
500	Internal Server Error	Unexpected server-side issue
503	Service Unavailable	API is temporarily in maintenance mode

Understanding Status Codes

• 2xx = Success - Your request worked
• 4xx = Client error - Check your request
• 5xx = Server error - Try again later or contact support

Response Format

Successful Responses

All successful API responses return JSON data under a data key:

{
  "data": {
    "id": "123",
    "name": "Example"
  }
}

For list endpoints, the response contains an array:

{
  "data": [
    {"id": "1", "name": "Item 1"},
    {"id": "2", "name": "Item 2"}
  ]
}

Supported Formats:

• JSON (all endpoints)
• CSV (select endpoints)

Error Responses

When an error occurs, the response includes details under an errors key:

{
  "errors": [
    {
      "message": "Invalid parameter value",
      "field": "date",
      "code": "INVALID_DATE"
    }
  ]
}

Rate Limits

To ensure API availability and prevent abuse, Spark enforces rate limits on all requests.

Current Limits

600 requests per sliding 60-minute window per account

How It Works

• Each API request counts toward your hourly limit
• The limit is calculated using a sliding 60-minute window
• As time passes, older requests fall out of the window and new quota becomes available

What Happens When You Hit the Limit

When you exceed the rate limit:

1. You'll receive a 429 Too Many Requests response
2. You'll need to wait until your limit resets

Best Practices

To stay within rate limits:

• Cache responses when possible to reduce API calls
• Batch requests instead of making individual calls
• Implement retry logic with exponential backoff
• Monitor your usage to identify optimization opportunities

Rate Limit Exceeded?

If you consistently hit rate limits, consider optimizing your integration or contact us at commercial@sparkcommodities.com to discuss higher limits.

Need Help?

If you encounter issues with requests or responses:

• Check this documentation for proper formatting
• Review the Authentication Guide
• Contact support at support@sparkcommodities.com