This guide covers how to handle errors from the Modash API. Proper error handling ensures your integration stays reliable and gives users clear feedback when something goes wrong.
You'll use these patterns throughout your integration to handle authentication failures, rate limits, bad requests, and server errors.
Error response format
When the API returns an error, the HTTP status code will be something other than 200 (typically a 4xx or 5xx code). Error details are formatted as JSON:
{
"error": true,
"code": "...",
"message": "..."
}Always use the code field for error handling, not the message. Messages may change over time without notice, but error codes remain stable.
Common error codes
Code | Meaning |
| Your API token is missing or invalid. Check your Authorization header and verify your key in the Developer Portal. |
| The request is malformed. Check for missing required parameters like search keywords, comment IDs, or hashtags. |
| You've exceeded the rate limit. Implement retry logic with exponential backoff. |
| An internal server error occurred. These are not billed. Retry after a short delay. |
Individual endpoints may have additional error codes documented in the API reference.
Handling rate limit errors (429)
Rate limiting errors always return HTTP status code 429. Handle them separately from other errors:
Pause and wait before retrying.
Use exponential backoff (1s, 2s, 4s, 8s...).
Set a maximum retry count.
Log rate limit hits to monitor your usage patterns.
Handling server errors (5xx)
Server errors are temporary and should be retried:
Wait a short time (1-2 seconds) before retrying.
Retry up to 3-5 times with increasing delays.
If the error persists, check the
/healthendpoint to confirm API availability.Failed requests are not billed, so retries don't cost extra credits.
Handling client errors (4xx)
Client errors indicate a problem with your request:
401 Unauthorized: Check your API key and Authorization header.
400 Bad Request: Review your request body and parameters. Make sure required fields are included.
404 Not Found: The requested resource doesn't exist. Verify the endpoint URL and any IDs in the request.
Do not retry 4xx errors automatically. Fix the underlying issue in your request first.
💡 Build a centralised error handler in your integration that categorises errors by HTTP status code. This makes it easy to apply the right retry logic and logging for each error type.
Best practices for error handling
Always check HTTP status codes first: Don't assume every response is successful.
Use the
codefield, notmessage: Error codes are stable, messages may change.Log errors with context: Include the endpoint, parameters, and timestamp to make debugging easier.
Set timeouts: Add request timeouts to avoid hanging connections.
Handle empty responses: Some endpoints may return empty data for private profiles or newly indexed creators.
For full API documentation, visit docs.modash.io. If you need help, email hello+api@modash.io.
FAQs
FAQs
Are failed requests billed?
No. If you receive a
500or other server error, no credits or requests are consumed. Only successful responses count against your quota.Should I retry 400 errors?
No. A
400error means your request is malformed. Fix the issue in your request body or parameters before retrying.How can I check if the API is down?
Use the
/healthendpoint. If it returns{"status": "ok"}, the API is operational. If it doesn't respond, the API may be experiencing downtime.What's the best way to debug unexpected results?
Log the full request (endpoint, headers, body) and response (status code, error code, message). Compare against the API documentation to identify mismatches.
Where can I report a persistent API error?
Email hello+api@modash.io with the error details, including the endpoint, request body, and the error response.