Below is a list of errors you might get when interacting with our API. Although not all possible errors and causes are listed, it is intended as a guidance, so you can determine what might be the cause and find additional resources that can help you resolve the situation.
| Error Code | Response | Possible Cause | Example | Solution |
| 400 | Bad Request | API payload request malformed | An otherwise properly configured API call (using JSON) is missing a parenthesis. | Make sure that your payload has the correct syntax. There are various third party JSON validator tools so try to validate the API call using one of these tools. |
| Using an endpoint that is not available on your account or for your plan type | Microsoft Azure account being unable to the Email Activity endpoint | Some of our partner reseller accounts do not have access to end points, so please check our documentation prior to using them! | ||
| 400 | Validation error | Incorrect payload content | Using parameters that are not available for a specific endpoint | Checking the specific endpoint being used in our API documentation, and ensuring the API parameters used are valid. |
| 401 | The provided authorization grant is invalid, expired, or revoked | API Key is invalid, has been deleted or permissions have changed | API Key stored in environmental variable stops working suddenly | Make sure that an API key being used to make an API call is available via "settings > api keys", and that it has the proper permissions for the endpoint being requested. |
| 401 | Maximum credits exceeded | You have reached the credit limit of your plan | Account in Free plans having used more than 100 daily credits. Accounts in other plans having reached more than 2.5x times their allotment | Upgrade to a higher volume plan or wait until the next reset period for credits on your current plan (reset is daily for Free Direct SendGrid accounts and monthly for most reseller plans) |
| 401 | Authenticated user is not authorized | Insufficient permissions | Teammate doesn’t have permissions for an API call to update supressions | Make sure that your Teammate account has the correct permissions, for this example. |
| 401 | The requestor's IP address is not whitelisted | Access attempt using a non-whitelisted IP address | IP Access management is enabled and the IP used for connection is not in the IP allow list | Ask another SendGrid account administrator or teammate with permissions to add your IP to the allow list or disable IP Access management on the account. |
| 401 | Account Disabled | Disabled Account | Account was Suspended, Banned or Deactivated by Consumer Trust (See Account Under Review) |
a) In most cases, an email is sent by Consumer Trust. Please look for it and reply. b) If no communication was sent (for example, suspension due to Dormancy), create a ticket with technical support, so we can help get SendGrid Consumer Trust support involved. |
| 403 | Access Forbidden | Insufficient Permissions | Teammate gets that error despite being told that the account has access to a feature | Make sure that your Teammate account has the correct permissions and that the API Key used has the correct scopes |
| Incorrect Scopes/Feature not available on the plan | Using an API Key with administration permissions to access the Email Validation end point |
1) Make sure that your plan allows access to Email Validation. 2) Make sure that you are using an API Key with the correct permissions |
||
| 403 | The from address does not match a verified Sender Identity | Missing Sender Authentication | Trying to use an email address for a domain that is not authenticated on the account | Single Sender authentication is for Marketing Campaigns. Email API and SMTP require Domain Authentication. Please authenticate the domain instead. |
| 405 | Not allowed | Trying to use an incorrect method during an API call | Trying to PATCH an existing Contacts Segment using the Segmentation v1 API instead of the V2 endpoint | Refer to our API documentation to check if the Method used applies to the endpoint you are trying to reach: https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api |
| 406 | Not acceptable | Unable to negotiate Accept content | Cannot accept a server response in JSON format (Accept: application/json) | Remove the specific Accept header and try to submit the request again. |
| 408 | Timeout | Query takes more than 20 seconds | Searching within a wide amount of contacts when no matches are quickly found | Try a different query using our Segmentation Query Language |
| 413 | Payload Too Large | Trying to upload a payload in excess of endpoint limits | Uploading a CSV with more than 1 million contacts | Refer to our API documentation to check if the limits of the endpoint you are trying to use: https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api |
| 429 | Too many requests/Rate limit exceeded | Exceeding limits of the endpoint you are trying to reach | Sending more than 7 requests per second to the Email Validation endpoint or more than 10 requests per minute to the Email Activity Endpoint | Make a test call so you can determine which are the X-Ratelimit-Limit, X-Ratelimit-Remaining and X-Ratelimit-Reset parameters for the endpoint. |
If the error you get is not described above, please don't hesitate to reach out to our Support team.