Errors

On error, data is null and errors holds one entry with a lowercase code, a message that says how to fix it, the field at fault when there is one, and a doc_url pointing here. Errors are never billed. Retry 429 and 500 after a pause; don't retry 400 to 404 without changing the request.

All error codes

Code HTTP What it means How to fix it

invalid_parameter 400 Something you sent can't be used, for example a GTIN with a wrong check digit or a limit outside its range. The error's field names the parameter. Correct the value named in field and send the request again. The message says what a good value looks like.

missing_parameter 400 A parameter the call needs wasn't sent, for example a part number without its manufacturer. Add the parameter named in field. Lookups need either gtin, or manufacturer and mpn together.

batch_too_large 400 A batch lookup held more items than your plan allows in a single call. Split the batch into smaller calls, or see the limit for your plan on the Plan page.

bad_request 400 The body couldn't be read as a JSON object. Send a JSON object with the header Content-Type: application/json.

validation_failed 422 Used by the dashboard and website APIs: a field failed validation. The error's field names it. Correct the field named in field. The message says what's expected.

unauthorized 401 The access token is missing, invalid or expired, or the client credentials are wrong. Get a fresh token from POST /v1/oauth/token with your client ID and secret from API > Keys (tokens last one hour). For MCP, reconnect the assistant.

csrf_invalid 403 Used by the dashboard APIs: a change was sent without the session's X-CSRF-Token header. Reload the page and try again. Custom scripts must send the token from /app-api/me.

forbidden 403 The token doesn't have the scope this call needs, the account isn't active, or the request came from somewhere this endpoint doesn't accept. Create a key with the scope the message names (API > Keys), or check the account status on the Plan page.

not_found 404 No such item, catalog, code or endpoint. A lookup miss is free. Keys that may queue research get a 202 'we're enhancing it now' instead (see Enrich on miss). Check the identifier or path. For items we don't have yet, use a live key with enrich:write so we research them.

method_not_allowed 405 This path exists, but not for the method you used. Use the method shown in the API reference for this path.

conflict 409 The thing you're changing is in a state that doesn't allow it, or a duplicate already exists. Reload the current state and try again.

unprocessable 422 The request is well formed but can't be carried out, for example queueing research with only a GTIN. Follow the message: for research, send the manufacturer and the part number.

no_active_plan 402 Live keys need an active plan. Choose a plan in Billing > Plan, or use a test key or the free-trial key.

trial_ended 402 The trial's tokens are used up and the plan you chose couldn't start. Check your card in Billing > Plan.

past_due 402 A payment failed and the grace period is over. Update your card in Billing > Payment methods.

spending_cap_reached 402 This call would pass the monthly spending cap you set. Raise or remove the cap in Billing > Plan, or wait for your next billing period.

plan_required_for_enrich 402 Researching an item we don't have yet needs a live key with enrich:write on a paid plan, or a free trial that allows research. Use a live key on a paid plan, or look items up without queue=true.

trial_limit_reached 402 The free-trial key's item allowance is used up. The error carries an upgrade_url. Move to a paid plan at the upgrade_url to keep using the Catavera API.

rate_limited 429 You sent more requests than your limit allows for now. Wait the number of seconds in the Retry-After header, then retry. Cache tokens for their full hour.

internal_error 500 An unexpected error. It has been logged. Retry after a short pause. If it keeps happening, email support with the request_id from meta.

Code	HTTP	What it means	How to fix it
`invalid_parameter`	400	Something you sent can't be used, for example a GTIN with a wrong check digit or a limit outside its range. The error's field names the parameter.	Correct the value named in field and send the request again. The message says what a good value looks like.
`missing_parameter`	400	A parameter the call needs wasn't sent, for example a part number without its manufacturer.	Add the parameter named in field. Lookups need either gtin, or manufacturer and mpn together.
`batch_too_large`	400	A batch lookup held more items than your plan allows in a single call.	Split the batch into smaller calls, or see the limit for your plan on the Plan page.
`bad_request`	400	The body couldn't be read as a JSON object.	Send a JSON object with the header Content-Type: application/json.
`validation_failed`	422	Used by the dashboard and website APIs: a field failed validation. The error's field names it.	Correct the field named in field. The message says what's expected.
`unauthorized`	401	The access token is missing, invalid or expired, or the client credentials are wrong.	Get a fresh token from POST /v1/oauth/token with your client ID and secret from API > Keys (tokens last one hour). For MCP, reconnect the assistant.
`csrf_invalid`	403	Used by the dashboard APIs: a change was sent without the session's X-CSRF-Token header.	Reload the page and try again. Custom scripts must send the token from /app-api/me.
`forbidden`	403	The token doesn't have the scope this call needs, the account isn't active, or the request came from somewhere this endpoint doesn't accept.	Create a key with the scope the message names (API > Keys), or check the account status on the Plan page.
`not_found`	404	No such item, catalog, code or endpoint. A lookup miss is free. Keys that may queue research get a 202 'we're enhancing it now' instead (see Enrich on miss).	Check the identifier or path. For items we don't have yet, use a live key with enrich:write so we research them.
`method_not_allowed`	405	This path exists, but not for the method you used.	Use the method shown in the API reference for this path.
`conflict`	409	The thing you're changing is in a state that doesn't allow it, or a duplicate already exists.	Reload the current state and try again.
`unprocessable`	422	The request is well formed but can't be carried out, for example queueing research with only a GTIN.	Follow the message: for research, send the manufacturer and the part number.
`no_active_plan`	402	Live keys need an active plan.	Choose a plan in Billing > Plan, or use a test key or the free-trial key.
`trial_ended`	402	The trial's tokens are used up and the plan you chose couldn't start.	Check your card in Billing > Plan.
`past_due`	402	A payment failed and the grace period is over.	Update your card in Billing > Payment methods.
`spending_cap_reached`	402	This call would pass the monthly spending cap you set.	Raise or remove the cap in Billing > Plan, or wait for your next billing period.
`plan_required_for_enrich`	402	Researching an item we don't have yet needs a live key with enrich:write on a paid plan, or a free trial that allows research.	Use a live key on a paid plan, or look items up without queue=true.
`trial_limit_reached`	402	The free-trial key's item allowance is used up. The error carries an upgrade_url.	Move to a paid plan at the upgrade_url to keep using the Catavera API.
`rate_limited`	429	You sent more requests than your limit allows for now.	Wait the number of seconds in the Retry-After header, then retry. Cache tokens for their full hour.
`internal_error`	500	An unexpected error. It has been logged.	Retry after a short pause. If it keeps happening, email support with the request_id from meta.

Still stuck? Email support@catavera.com with the request_id from meta.