Home · Docs · Schemas · ApiError
ApiError — the shape of every refusal
Every 4xx and 5xx from the API carries this object. The `error` value is a stable string you can branch on; the extra fields appear only for the errors that have something to report.
ApiError has 9 fields: 0 nullable, 0 guaranteed by the contract's required list. Every number on this page is counted from the field map at render time — none of them is written down.
The contract has a typo in this schema's `required` list: it names `erro` (Portuguese), which is not one of the nine properties. The field that always ships is `error`. Recorded at app/api/v1/openapi.json/route.js:530, measured 02/10/2026.
Fields
| Field | Type | Nullable | Required |
|---|---|---|---|
error | string | no | no |
message | string | no | no |
http | integer | no | no |
limit | integer | no | no |
renews_at | string | no | no |
credits_balance | integer | no | no |
needed | integer | no | no |
spent_this_month | integer | no | no |
cap | integer | no | no |
9 rows above, 5 of them with a transcription from the contract and 1 with a note of ours.
What the fields mean
Only the fields with something measured or decided about them appear here. A field whose name and type say everything gets no paragraph, rather than a generic one.
error
Closed set of 9 values — branch on these, never on message text: chave_ausente, chave_invalida, intervalo_invalido, parametro_invalido, sem_creditos, teto_estourado, endpoint_indisponivel, metodo_invalido, indisponivel.
http
From the contract: Echoed by errors that originate in the database. The real HTTP status is authoritative — do not branch on this field.
Our note: Present only when the refusal originates in the database. /api/v1/movers/{niche} without a key answers {"error":"chave_invalida","http":401} and /api/v1/trends/{niche} answers {"error":"chave_ausente"} with no http — the first refuses inside Postgres, the second refuses before reaching it. Both measured 02/10/2026.
credits_balance
From the contract: `sem_creditos` only: credits left on the key.
needed
From the contract: `sem_creditos` only: credits the call would cost.
spent_this_month
From the contract: `teto_estourado` only: credits spent this month.
cap
From the contract: `teto_estourado` only: the monthly ceiling.
How this page stays true
The field list, the two flags and the closed value sets are generated from the contract this API serves, and a test compares them against the live /openapi.json in both directions: a field in the contract with no documentation fails, a documented field the contract does not have fails, and a wrong nullable or required fails. The prose marked our note is not covered by that test — it is authored, and labelled so you can tell.
The machine-readable source is at /openapi.json. If you are generating a client, use that rather than this page.
The other 7 schemas
SeriesPoint · Item · Mover · Author · PostItem · PostsEnvelope · ProfileEnvelope