Errors
Every error has the same shape, with a stable name you can rely on in code and a message for people:
{ "statusCode": 429, "name": "daily_quota_exceeded", "message": "Your team has used all 100 checks for today." }The Perspective-compatible endpoint answers in Google's { "error": { "code", "message", "status" } } shape instead.
name |
Status | What it means and how to fix it |
|---|---|---|
missing_api_key |
401 | Send your key in the Authorization header: "Authorization: Bearer sg_live_…". Perspective clients may send it as ?key= instead. |
invalid_api_key |
403 | The key is unknown, revoked, or past its rotation overlap. Create a new key on the API keys page and update your server's environment variable. |
restricted_api_key |
403 | This key can't call this endpoint. Check-only keys can only check messages, and test keys can only manage test keys. Use a full-access live key. |
admin_required |
403 | Only team admins can do this. Ask an admin of the team, or ask one to make you an admin. |
email_not_verified |
403 | Verify your email address first: sign out and sign in again with the code we email you. |
free_team_limit_reached |
403 | You already have two teams on the Free plan. Upgrade one of them, or work in an existing team. |
not_found |
404 | The endpoint or the resource doesn't exist, or belongs to another team. Check the path and the ID. |
method_not_allowed |
405 | The endpoint doesn't accept this HTTP method. The docs list the methods for each endpoint. |
idempotency_key_reused |
409 | This Idempotency-Key was already used with a different body. Use a new key for each distinct request. |
idempotency_key_in_use |
409 | A request with this Idempotency-Key is still running. Wait a moment, then retry with the same key. |
already_processed |
409 | This request already succeeded, but its response showed a secret once, so it isn't repeated. List your API keys or webhooks to find what it created, or send a new request with a new Idempotency-Key. |
validation_error |
422 | A field is missing or has the wrong type. The response message names the field; compare your request body with the docs. |
text_too_long |
422 | Send at most 10,000 characters per check. Check the part of the text people will see, or split long text into several checks. |
api_key_limit_reached |
422 | The team has as many keys as its plan allows. Revoke keys you no longer use on the API keys page. |
webhook_limit_reached |
422 | The team has as many webhook endpoints as its plan allows. Delete one you no longer use, or upgrade for more. |
member_limit_reached |
422 | The team has as many members as its plan allows, counting open invitations. Remove a member or cancel an invitation, or upgrade. |
overage_not_available |
422 | Pay-as-you-go checks come with Pro and Scale. Upgrade the team to turn them on. |
rate_limit_exceeded |
429 | Too many requests at once. Wait the seconds in retry-after, spread requests out, or send up to 100 messages in one batch request. |
daily_quota_exceeded |
429 | The team used all of today's checks. They reset at 00:00 UTC; upgrade for a higher limit. |
monthly_quota_exceeded |
429 | The team used all of this period's checks. Upgrade, or turn on pay-as-you-go on the Usage page. |
overage_cap_reached |
429 | Pay-as-you-go reached the cap the team set. Raise the cap on the Usage page, or wait for the next period. |
internal_server_error |
500 | Something failed on our side. Retry with the same Idempotency-Key; if it keeps happening, contact us with the request ID. |
model_unavailable |
503 | Checks that need the AI model are briefly unavailable. Retry after the seconds in retry-after; test keys keep working. |
capacity_paused |
503 | Checks that need the AI model are paused for a moment. Rules, cached results and test keys keep working; retry after retry-after. |
billing_unavailable |
503 | Online payments aren't switched on for Spamgone yet. Contact us, and we'll change your plan by hand. |