Troubleshoot API and webhooks

Start with the evidence MailGraf already records. For API requests, note the status code and the detail value in the response. For webhooks, open the failed record under Recent deliveries before sending another test.

Diagnose an API response

Open Settings > API keys > API request monitor to match the request with its key prefix, resource, IP address, response code and time. Do not copy the full API key into logs or support messages.

401 Unauthorized

The request has no bearer token or the API key is invalid or revoked.

• Confirm that the header is Authorization: Bearer mg_live_....
• Check for an extra space, quotation mark or truncated value in the service configuration.
• If the full key was lost, create a replacement. MailGraf cannot reveal it again.
• If the key may have leaked, follow API key security and revoke it.

Repeated failed authentication from the same IP address can cause a temporary lock. Correct the key before retrying.

403 Forbidden

The MailGraf account does not currently have public API access. Check the account's plan and API access before changing the request body.

404 Not Found

The path may be wrong or the requested list, campaign or other resource does not belong to the account connected to the key. Confirm both the endpoint path and resource ID. A key cannot read another account's data.

422 Unprocessable Content

The request reached the endpoint but one or more values failed validation. Read the response's detail field. It may contain a single explanation or a list of field-level issues. Correct the named values rather than resending the same body.

429 Too Many Requests

The key has exceeded its request limit. Read the Retry-After response header and wait that many seconds. Queue or spread requests instead of retrying every failed request at once.

503 Service Unavailable

MailGraf could not apply rate-limit protection at that moment, so the API failed closed. Retry with a short backoff. If the response continues, keep the response time and affected path for support.

Check a webhook endpoint

If MailGraf will not save an endpoint, confirm that the URL uses HTTPS and its hostname resolves to a public IP address. Localhost, private network addresses and reserved addresses are rejected. MailGraf checks the address again during delivery, so a later DNS change can also stop deliveries.

For a saved endpoint, open Recent deliveries and follow the result:

• No 2xx response: inspect the receiving service's status and logs. A 401 or 403 here comes from that service, not from MailGraf's public API.
• 3xx response: replace the endpoint URL with the final HTTPS destination. MailGraf does not follow redirects.
• Timeout: queue the work and return 2xx within seven seconds. Complete the slow work after acknowledging the event.
• Signature mismatch: use the endpoint's current Signing secret and verify the exact raw body before parsing JSON. Follow Verify webhook signatures.

A test event makes one attempt. Normal events retry automatically. After correcting the cause, click Retry now on a failed delivery to start a new cycle.

Record useful evidence

If the problem continues, keep the approximate UTC time, API path or webhook event, response code and the relevant monitor or delivery record. Never share an API key or webhook signing secret.

Where the full reference lives

Use the API reference for endpoint paths, request fields, response schemas and the status codes each operation can return.