API Basics
Introduction
Sunlight provides a powerful and flexible API that allows you to integrate Sunlight's functionality into your application. Whether you're performing card switches, managing customizations, or configuring webhooks, the Sunlight API offers a wide range of capabilities to enhance your user experience. In this guide, we'll provide a high-level overview of how to work with Sunlight APIs, including authentication, versioning, and error handling.
Authentication
All Sunlight API requests require authentication using an API key and a secret key. These keys are used to identify and authorize your application when making requests to the Sunlight API.
To obtain your API credentials, please reach out to us at [email protected]
When making an API request, you must include the following headers for authentication:
"x-api-key: YOUR_API_KEY"
"x-secret-key: YOUR_SECRET_KEY"
Additionally, you need to specify the API version you wish to use. The default version is 1. Use the following header to specify the version:
"x-version: 1"
Example
Here's an example of an authenticated API request using curl
:
curl --request GET \
--url https://api.sunlightapi.com/api/customizations/list \
--header 'accept: application/json' \
--header 'x-api-key: <YOUR-API-KEY>' \
--header 'x-secret-key: <YOUR-SECRET-KEY>' \
--header 'x-version: 1'
Error Handling
When working with the Sunlight API, it's important to handle errors appropriately. The API may return error responses with specific error codes and messages. The error response is provided in JSON format with the following structure:
{
"error_code": string,
"error_message": string
}
Below, we've grouped the possible error responses by their corresponding HTTP status codes. Each error is described by its error_code
and error_message
.
400 Bad Request
Error Code | Error Message |
---|---|
1001 | api key header is missing |
1002 | secret key header is missing |
1003 | version header is missing |
1010 | endpoint not found for the specified version |
1030 | invalid input parameters |
401 Unauthorized
Error Code | Error Message |
---|---|
1006 | invalid api key |
1007 | invalid secret key |
1011 | inactive endpoint |
1012 | customer not found |
1013 | unauthorized_endpoint |
429 Too Many Requests
Error Code | Error Message |
---|---|
1020 | daily quota limit exceeded |
You can use this information to diagnose failed transactions and fine-tune your exception-handling capabilities. By understanding the different error codes and messages, you can provide meaningful feedback to users and handle errors gracefully in your application.
Versioning and Backwards Compatibility
The Sunlight API is designed with versioning and backwards compatibility in mind. We strive to avoid making breaking changes to the API without reaching out to you first. We're continually making backwards-compatible changes to the API. Examples of things we do not consider "breaking" include:
- Adding new optional request parameters to existing API methods.
- Adding new properties to existing API responses.
- Changing the order of properties in existing API responses.
- Adding new API resources or methods.
- Changing the length or format of opaque strings, such as resource IDs, error messages, and other human-readable strings.
Updated 8 months ago
By following these API basics, you can effectively work with the Sunlight API and take advantage of its powerful features. As you continue to explore the capabilities of the Sunlight API, be sure to review the full API documentation and guides for additional information on how to leverage the various endpoints and features available.