Real-Time API: API errors, limits, and returns
Technical guide to interpreting Real-Time API errors, usage limits, and responses without impacting forms or integrations.
Priscila G.
Last Update 10 giorni fa
SafetyMails' Real-Time API is designed to operate stably even in high-volume scenarios. The most frequently asked questions related to the API do not involve email validation itself, but rather return errors, usage limits, and expected API behavior in specific situations.
This document centralizes this information and explains how to correctly interpret each return, avoiding confusion between technical errors, plan limits, and normal system operation.
How we handle each Real-Time API request
Before performing any email verification, each request received by the Real-Time API undergoes a technical and compliance validation step. At this stage, the system assesses whether the request is eligible for processing, considering criteria such as authentication, call origin, usage limits, and credit availability.
Only after this preliminary analysis is the request forwarded to the email verification stage. If any of these initial validations fail, the API immediately returns a technical error without performing the verification.
Only after this preliminary analysis is the request forwarded to the email verification stage. If any of these initial validations fail, the API immediately returns a technical error without performing the verification.
This flow ensures stability, protection against misuse, and predictability in API behavior, without causing form blocking or integration interruptions.
Erros de retorno da API (Success = false)
The messages below are only displayed when the Success field returns as false in the API response. In such cases, the query was not performed successfully, and the Msg field provides the reason for the failure.
These errors are related to authentication issues, incorrect parameters, API origin, lack of credits, or exceeded limits.
Example of an error return Below is an example of an API response when a technical error occurs and the Success field returns as false:{
"Success": false,
"Email": "testeemail@safetymails.com",
"Referer": "www.safetymails.com",
"Status": "PENDENTE",
"Advice": "Unknown",
"Msg": "Referer inválido"
}
"Success": false,
"Email": "testeemail@safetymails.com",
"Referer": "www.safetymails.com",
"Status": "PENDENTE",
"Advice": "Unknown",
"Msg": "Referer inválido"
}
In this scenario, the request was interrupted at the preliminary validation stage (invalid source), and no email verification was performed.
API usage error table
| HTTP Code | Erro | Description |
|---|---|---|
| 400 | Invalid parameters | Incorrect or non-existent parameters or access keys in the request. |
| 401 | Invalid API Key | The access key you entered is invalid or does not exist. |
| 402 | No funding to conduct the research | The account does not have sufficient credits to perform the query. |
| 403 | Different origin from the one registered | The request is being made from a source other than the one registered in the account. |
| 406 | Invalid or inactive source ticket | The API source is inactive and needs to be activated correctly in the dashboard. |
| 429 | Consultation limit exceeded | The limit of queries per minute, hour, or day has been exceeded. |
When Success = false, no validation is performed.
Sandbox vs. Production
Sandbox
• Environment intended exclusively for testing
• Does not reflect the actual limits of the contracted plan
• May return simulated responses
• Should not be used in active forms
• Consumes credits
• Applies limits per minute, hour, and day
• Accurately reflects the behavior described in this document
Errors observed in production should not be compared with tests performed only in the sandbox.
• Environment intended exclusively for testing
• Does not reflect the actual limits of the contracted plan
• May return simulated responses
• Should not be used in active forms
Production
• Real usage environment• Consumes credits
• Applies limits per minute, hour, and day
• Accurately reflects the behavior described in this document
Errors observed in production should not be compared with tests performed only in the sandbox.
API usage limits
Each plan has specific limits for:
• requests per minute
• requests per hour
• daily requests
These limits vary according to the plan contracted and are part of the API fair use rules. The official values are described in the platform's Terms of Use: https://www.safetymails.com/terms-of-use/
• requests per minute
• requests per hour
• daily requests
These limits vary according to the plan contracted and are part of the API fair use rules. The official values are described in the platform's Terms of Use: https://www.safetymails.com/terms-of-use/
What happens when the limit is exceeded
When API usage exceeds the limit allowed by the plan:
• forms are not blocked
• the API continues to respond
• requests that have exceeded the limit are given a PENDING status
• the behavior is visible in the API daily consumption chart
This mechanism exists to preserve the end user experience, prevent front-end failures, and flag usage that is not in compliance with the contracted plan.
• forms are not blocked
• the API continues to respond
• requests that have exceeded the limit are given a PENDING status
• the behavior is visible in the API daily consumption chart
This mechanism exists to preserve the end user experience, prevent front-end failures, and flag usage that is not in compliance with the contracted plan.
API data does not appear
When API data does not appear as expected, it is usually related to:
• incorrect use of the environment (sandbox vs. production)
• invalid authentication
• response interpretation error
• requests impacted by temporary limits or API expiration due to non-confirmation of monthly or annual subscription payment (cancellation occurs after 3 days of non-confirmation of payment)
Before escalating, it is important to validate the environment used, the API Key, and the integration logs.
• incorrect use of the environment (sandbox vs. production)
• invalid authentication
• response interpretation error
• requests impacted by temporary limits or API expiration due to non-confirmation of monthly or annual subscription payment (cancellation occurs after 3 days of non-confirmation of payment)
Before escalating, it is important to validate the environment used, the API Key, and the integration logs.
Visible limits on the consumption chart (lilac color)
This scenario does not represent a technical error in the API.
When API usage exceeds plan limits:
• consumption appears on the daily chart marked in lilac
• associated requests remain in PENDING status
• forms are not blocked
• there is no API interruption
This behavior exists to signal non-compliant usage without impacting operation.
When API usage exceeds plan limits:
• consumption appears on the daily chart marked in lilac
• associated requests remain in PENDING status
• forms are not blocked
• there is no API interruption
This behavior exists to signal non-compliant usage without impacting operation.
When to escalate to technical support
This document should be your first point of reference.
If, after reading this article, you still have questions, technical support is available to assist you during business hours.
• the error persists after following this guide
• there are signs of a specific implementation error
• the behavior does not match that described in this document
In most cases, adjustments to the integration logic, request volume, or contracted plan will resolve the issue.
If, after reading this article, you still have questions, technical support is available to assist you during business hours.
• the error persists after following this guide
• there are signs of a specific implementation error
• the behavior does not match that described in this document
In most cases, adjustments to the integration logic, request volume, or contracted plan will resolve the issue.