4XX API Errors and Troubleshooting Suggestions

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

Have more questions? Submit a request