Error Codes
HTTP status codes and error responses returned by the Phrasly API.
Overview
The Phrasly API uses standard HTTP status codes to indicate the success or failure of every request. When an error occurs, the response body contains a JSON object with an error field that describes what went wrong. This makes it easy to handle errors programmatically in any language or framework.
Successful requests return a 200 status code. Client errors (invalid input, missing authentication, exhausted credits) return 4xx codes. Server errors (temporary outages or internal failures) return 5xx codes. Your integration should handle each category appropriately to provide a smooth user experience.
Status Codes
All errors return JSON with an error field describing what went wrong. Below is a complete list of status codes returned by the Humanization API and AI Detection API.
Success
Request completed successfully.
Bad Request
Missing or invalid parameters (text too short, invalid mode).
Unauthorized
Missing or invalid API key.
Forbidden
No active subscription on the account.
Credits Exhausted
Credits used up. Enable autopay or wait for the next billing period.
Service Unavailable
AI service temporarily unavailable. Retry after a few seconds.
Error Response Format
All error responses follow a consistent JSON format. The error field contains a human-readable description of the problem that can be used for debugging or displayed to end users.
{
"error": "Description of what went wrong"
}Error Handling Best Practices
Building robust error handling into your API integration ensures a reliable experience for your users and prevents unexpected failures in production. Follow these recommendations:
- Always check the HTTP status code before parsing the response body. A 200 status confirms the request was processed successfully.
- For 400 errors, validate your request parameters before retrying. Common causes include text that is too short, too long, or an invalid mode value.
- For 401 errors, verify that your API key is correct and included in the x-api-key header. Check that the key has not been revoked from your dashboard.
- For 403 errors, confirm that your account has an active subscription. This error occurs when the subscription has expired or been cancelled.
- For 429 errors, your monthly credits have been exhausted. Enable autopay in your dashboard settings to avoid service interruptions, or wait for the next billing cycle.
- For 503 errors, implement exponential backoff with retry logic. The AI service may be temporarily unavailable due to high demand or maintenance. Retry after 2-5 seconds.
- Log all error responses with timestamps and request details. This makes it easier to debug integration issues and monitor API health over time.
Recommended Retry Strategy
For transient errors (503 Service Unavailable), we recommend implementing an exponential backoff strategy. Start with a 2 second delay on the first retry, then double the delay for each subsequent attempt, up to a maximum of 3 retries.
| Attempt | Delay | Action |
|---|---|---|
| 1st retry | 2 seconds | Retry the request |
| 2nd retry | 4 seconds | Retry the request |
| 3rd retry | 8 seconds | Retry the request |
| After 3rd | - | Log the error and alert your team |