← Docs

Errors & Troubleshooting

All errors return a structured JSON object for programmatic handling.

Error Response Format

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "No credits remaining. Current balance: 0",
    "action": "Purchase credits via POST /api/checkout",
    "docs": "https://inbox.dog/docs/errors#INSUFFICIENT_CREDITS"
  }
}

Every error includes a machine-readable code, a human-readable message, a suggested action, and a link to relevant docs.

Error Codes

Code HTTP Description Action
INVALID_CREDENTIALS 401 Invalid client_id or client_secret Check your API credentials
INSUFFICIENT_CREDITS 402 No credits remaining Purchase credits via POST /api/checkout
VALIDATION_ERROR 400 Missing or invalid request parameters Check the required fields for the endpoint
STATE_NOT_FOUND 400 OAuth state expired or invalid Restart the OAuth flow (states expire after 10 minutes)
AUTH_CODE_NOT_FOUND 400 Authorization code expired or already used Restart the OAuth flow (codes expire after 5 minutes)
TOKEN_EXCHANGE_FAILED 500 Google token exchange failed Retry the request or check Google OAuth configuration
NOT_FOUND 404 Resource not found Check the endpoint URL and parameters
OAUTH_ERROR 400 User denied consent or Google returned an error Prompt the user to try again
INTERNAL_ERROR 500 Internal server error Retry the request

Failure Modes

Common failure scenarios and how to handle them:

User denies Google consent

The callback redirects with ?error=access_denied. No code is returned. No credit is charged. Prompt the user to try again.

Authorization code expires

Codes are valid for 5 minutes after the callback. If you call POST /oauth/token after expiry, you get AUTH_CODE_NOT_FOUND. No credit is charged. Restart the flow.

OAuth state expires

If the user takes more than 10 minutes on the Google consent screen, the state expires. The callback fails with STATE_NOT_FOUND. Restart the flow.

Access token expires

Access tokens expire after 1 hour (set by Google). Use the refresh_token to get a new one. See Token Refresh guide. This is free.

Refresh token revoked

If the user revokes your app's access in their Google account settings, the refresh token becomes invalid. You'll get TOKEN_EXCHANGE_FAILED. The user must re-authenticate through the full OAuth flow.

Out of credits

Token exchange returns INSUFFICIENT_CREDITS (402). Purchase more via POST /api/checkout, or self-host for unlimited usage.