PostGrad
For subscribers

Handle errors gracefully

Every error code PostGrad's API can return, what it means, and how to recover without surfacing a stack trace to your end user.

Every PostGrad response follows the same envelope: { data, error }. One of those two is always null. When error is populated, it has a code, a message, and sometimes details. Knowing the codes up front means your agent never surprises you in production.

Before you start: you've made at least one successful call (Make your first API call).

Open the Usage page to see errors alongside successes

The Usage page showing a mixed list of successful calls (200) and failures (401, 403, 429).
The Usage page showing a mixed list of successful calls (200) and failures (401, 403, 429).

401 UNAUTHORIZED — your key is wrong

An example 401 response body with the error code UNAUTHORIZED and the message 'Invalid API key.'
An example 401 response body with the error code UNAUTHORIZED and the message 'Invalid API key.'

403 TIER_INSUFFICIENT — your plan doesn't cover this

An example 403 response with error code TIER_INSUFFICIENT and a help_url field pointing to the change-tier walkthrough.
An example 403 response with error code TIER_INSUFFICIENT and a help_url field pointing to the change-tier walkthrough.

This replaces what used to be a silent fallback to keyword mode — if you were relying on the fallback, audit your callers and either handle the 403 or upgrade.

403 FEED_NOT_SUBSCRIBED — access to this feed needs a subscription

An example 403 response for FEED_NOT_SUBSCRIBED with a link to the marketplace for that specific feed.
An example 403 response for FEED_NOT_SUBSCRIBED with a link to the marketplace for that specific feed.

429 RATE_LIMIT_EXCEEDED — too many calls per minute

An example 429 response with a Retry-After header and a message describing the per-minute cap.
An example 429 response with a Retry-After header and a message describing the per-minute cap.

500 and 503 — the platform is having a moment

An example 5xx response with a generic INTERNAL_ERROR code and a link to the status page.
An example 5xx response with a generic INTERNAL_ERROR code and a link to the status page.

Use the help_url field to deep-link users out of errors

A code snippet showing how to read error.help_url from the response and surface a 'Learn more' button to the end user.
A code snippet showing how to read error.help_url from the response and surface a 'Learn more' button to the end user.

What's next

Errors are handled. Now make the rest of the integration bulletproof:

  • Verify with Usage — Usage page is the live log for every call; errors show up within seconds.
  • Upgrade if needed — Upgrade or downgrade your tier if you're routinely hitting TIER_INSUFFICIENT.
  • Full reference — the /docs area covers every endpoint's full error shape.

Understand the three search modes

Keyword, semantic, hybrid — what each one does, which tier unlocks it, and when to use one over another.

Enable and manage notifications

Turn on the bell, set per-category preferences, and configure quiet hours so PostGrad only pings you when it actually matters.

On this page

What's next