This troubleshooting section explains how the Removit asynchronous API reports authentication failures, validation errors, job lookup issues, and temporary infrastructure problems.
Use it to interpret status codes and improve the reliability of your API backend integration and job polling logic.
These categories help you decide whether the issue should be retried, corrected in the request payload, or escalated operationally.
Malformed JSON, missing parameters, incompatible field combinations, or invalid URL inputs.
Authentication failures, missing credits, or job lookup errors that depend on account or workflow state.
Temporary service unavailability or terminal processing failures that may need retries or escalation.
These are the errors most integrations should expect and map explicitly in backend logic.
Returned when the API key is absent or invalid. - The request does not send X-API-Key or Authorization: Bearer. - The API key value is invalid or no longer accepted.
{
"error": "unauthorized",
"message": "API key invalid"
}Returned when the request is syntactically valid but fails business validation. - job_id is missing on /status. - mode=params is sent without params. - file_url is invalid. - file and file_url are sent together.
{
"error": "validation",
"details": {
"file": ["You must provide either file_url or file"],
"mode": ["The value you selected is not a valid choice."]
}
}Returned when the account does not have enough credits to create the requested job. - The current account balance is insufficient. - The workflow should be retried only after credits are restored.
{
"error": "insufficient_credits"
}Returned when the requested job cannot be found from the provided job_id. - The job_id is wrong or unknown. - The client is polling the wrong environment or account context.
{
"error": "not_found"
}Returned when the service is temporarily unavailable or an upstream dependency is failing. - A temporary infrastructure issue affects job creation or job status retrieval. - The integration should retry with backoff and monitor escalation thresholds.
{
"error": "credits_service_unavailable"
}When processing fails definitively, the status payload can include a rejected status and refund information.
This type of response indicates a terminal failure rather than a pending or retriable state.
{
"error": "Service unavailable",
"code": 503,
"status": "rejected",
"refund": "done"
}Refund information helps backend systems decide whether a manual billing review is necessary.
The refund was successfully processed.
The refund had already been processed earlier.
The refund was not confirmed and should be reviewed operationally.
Use this table when the request succeeds technically but the workflow does not move as expected.
| Symptom | Probable cause | Recommended action |
|---|---|---|
| status=queued for a long time | Backlog or job not yet persisted in the visible state layer. | Continue polling with backoff before escalating. |
| status=pending_* for a long time | External image processing is still running. | Review retries, timeout thresholds, and business SLA expectations. |
| 422 background image must be an http/https URL | The file_url value is invalid or not public. | Send a public HTTP or HTTPS image URL. |
| final_url = null | The job is not finished yet. | Keep polling until state=done. |
This compact catalog helps backend teams map status codes to logging, retry, and escalation rules.
| Code | Endpoint | Meaning |
|---|---|---|
| 200 | /status | Job status successfully returned. |
| 202 | /upload, /status | Job accepted or not yet persisted in the final visible state. |
| 400 | /upload | Invalid JSON or malformed request body. |
| 401 | /upload, /status | Authentication is missing or invalid. |
| 402 | /upload | Insufficient credits. |
| 404 | /status | The requested job was not found. |
| 422 | /upload, /status | Validation error on payload or query parameters. |
| 500 | /status | Internal processing error. |
| 502 | /status | External API failure. |
| 503 | /upload, /status | Temporary service unavailability. |