API Troubleshooting
This page covers common problems when using the Soku Public API and how to resolve them.
API Key Not Working
If your API requests are returning 401 Unauthorized:
Check the key is correct
Make sure you are using the full API key exactly as it was displayed when you created it. Keys start with sk_live_ followed by a long string of characters.
The key must be sent in the Authorization header as a Bearer token:
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
| Mistake | Example | Fix |
|---|
Missing Bearer prefix | Authorization: sk_live_... | Add Bearer before the key. |
| Extra spaces | Authorization: Bearer sk_live_... | Remove extra spaces. |
| Key in query string | ?api_key=sk_live_... | Move the key to the Authorization header. |
| Wrong header name | X-API-Key: sk_live_... | Use Authorization as the header name. |
Check that the key has not been revoked
Go to Settings > API in your Soku dashboard and verify that the key is still listed as Active. If it was revoked, generate a new one.
Regenerate the key
If you suspect the key was copied incorrectly or corrupted, revoke it and generate a new one. Remember that the full key is only shown once at creation.
Rate Limited (429 Too Many Requests)
If you receive a 429 response, you have exceeded Soku’s API rate limits.
How to fix:
- Slow down your requests. Reduce the frequency of API calls.
- Check the rate limit headers in the response to see your current limits and when they reset.
- Implement backoff logic. When you receive a 429, wait before retrying. Use exponential backoff for best results.
API rate limits are separate from credits. Rate limits control how many requests you can make per minute, while credits track AI operation usage. See Rate Limits for specific limits by plan.
Wrong Base URL
All Soku API requests should be sent to the correct base URL. If you are getting connection errors or unexpected responses, verify your base URL.
Make sure you are using the production API URL provided in the API Introduction. Do not add trailing slashes or extra path segments to the base URL.
If you are sending request bodies (POST, PUT, PATCH requests) and receiving 400 Bad Request errors, you may be missing the Content-Type header.
For JSON request bodies, always include:
Content-Type: application/json
| Mistake | Fix |
|---|
No Content-Type header at all | Add Content-Type: application/json to your request headers. |
Using text/plain | Change to application/json. |
| Sending form data instead of JSON | Encode your body as JSON and set the correct Content-Type. |
| Body is not valid JSON | Validate your JSON with a tool like jsonlint.com. |
Common API Error Codes
| Status Code | Meaning | Common Cause |
|---|
| 400 | Bad Request | Missing required fields, invalid JSON body, or wrong Content-Type. |
| 401 | Unauthorized | Invalid, revoked, or missing API key. |
| 402 | Payment Required | Insufficient credits for the requested operation. |
| 403 | Forbidden | Subscription inactive, trial expired, or action not allowed on your plan. |
| 404 | Not Found | The requested resource does not exist. Check your endpoint URL and resource IDs. |
| 429 | Too Many Requests | Rate limit exceeded. Slow down and retry with backoff. |
| 500 | Internal Server Error | Server-side issue. Retry after a short wait. |
Debugging Tips
Use a tool like cURL or Postman
Test your API calls in isolation using cURL, Postman, or a similar HTTP client. This helps you rule out issues in your application code.
Example cURL request:
curl -X GET https://api.mysoku.io/v1/posts \
-H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json"
Check the response body
Soku API error responses include a JSON body with details about what went wrong. Always read the error message — it usually points directly to the problem.
Verify request and response in your logs
Log the full request (URL, headers, body) and response (status code, body) in your application. This makes it much easier to diagnose issues.
Never log your full API key in production logs. Mask or redact it if you include it in log output.
Still Having Issues?
If you have worked through the steps above and are still experiencing API problems:
- Double-check the API Reference for the endpoint you are using.
- Verify your account status and subscription in Settings > Billing.
- Contact Soku support with the following details:
- The endpoint URL you are calling
- The HTTP method (GET, POST, etc.)
- The status code and error message you received
- The approximate timestamp of the failed request
Related Pages
