# Errors

URL: https://neattrim.com/docs/errors

Every Neattrim API error code, its HTTP status, whether to retry, and how to fix it.

An error answers with the HTTP status below and a JSON body.

```json
{
  "error": {
    "code": "LIMIT",
    "message": "This call needs more allowance than you have left.",
    "fix": "Wait for the reset or add time.",
    "reason": "allowance",
    "meter": "voice_ai",
    "resetsAt": "2026-12-01T00:00:00Z",
    "requestId": "req_123"
  }
}
```

`code` is stable and safe to branch on. `message` and `fix` are for people and may change. Quote `requestId` when you contact support. The SDKs raise a typed error with these fields.

| Code | HTTP status | Retry | Reasons | How to fix it |
| --- | --- | --- | --- | --- |
| `BAD_REQUEST` | 400 | no | `test_mode_sample_only`, `device_only`, `no_face`, `client_outdated` | Read `param` in the error to find the field, correct it and send the request again. With a test key, use only the sample files named in the error. |
| `UNAUTHENTICATED` | 401 | after re-auth | `missing`, `invalid`, `key_revoked`, `token_expired`, `reauth_required` | Send `Authorization: Bearer <key>` with a key that is valid and not revoked. Sign in again if you use OAuth and the token expired. |
| `INACTIVE` | 401 | no | `expired`, `refunded`, `revoked`, `payment_failed`, `suspended` | The account or plan is no longer active. Open your account to see why, then renew or fix the plan. |
| `NEEDS_PLAN` | 402 | after purchase | `paid_feature`, `subscribers_only` | The feature is part of a paid plan. Choose a plan on the pricing page, then send the request again. |
| `LIMIT` | 402 | after resetsAt or a purchase | `allowance`, `key_cap`, `storage_cap`, `no_free_allowance`, `network`, `spend_ceiling` | Read `reason`, `meter` and `resetsAt`. Wait for the reset, buy a top-up or a plan, or lower the size of the job. |
| `DECLINED` | 402 | user action | `provider_decline` | The payment provider declined the payment. Use another payment method. |
| `FORBIDDEN_SCOPE` | 403 | no | `missing_scope`, `web_only` | The key or token lacks a scope. Create a key with the scope named in `param`. Voice cloning is available only in the web app. |
| `VOICE_PROTECTED` | 403 | no | none | The voice is protected and cannot be used. Choose a different voice. |
| `NOT_FOUND` | 404 | no | `result_lost` | The id does not exist for this account, or the result was removed. Check the id and run the job again if the result is lost. |
| `CONFLICT` | 409 | no | none | The request conflicts with the current state. Fetch the current state and try again. |
| `IDEMPOTENCY_MISMATCH` | 409 | no | none | You reused an `Idempotency-Key` with a different body. Use a new key for a new request. |
| `DEVICE_LIMIT` | 409 | no | none | The account has reached its device limit. Remove a device you no longer use. |
| `ALREADY_SUBSCRIBED` | 409 | no | none | The account already has this plan. Change or manage the plan from the billing page. |
| `QUOTE_CHANGED` | 409 | after a new quote | none | The price changed since the quote. Ask for a new quote and confirm it. |
| `BILLING_OP_IN_PROGRESS` | 409 | later | none | A billing change is still running. Wait a moment and try again. |
| `RESUME_FIRST` | 409 | after resume | none | The subscription is paused. Resume it, then send the request again. |
| `PAYMENT_ISSUE` | 409 | after fixing payment | none | The last payment failed. Fix the payment method on the billing page, then try again. |
| `GONE` | 410 | no | none | The resource was deleted or has expired and cannot come back. Create it again. |
| `EXPIRED` | 410 | no | `input_expiring` | The input or link expired. Upload the file again or ask for a new link. |
| `TOO_BIG` | 413 | no | `resolution` | The file is larger than your plan allows. The error states the limit. Send a smaller file, or move to a plan with a higher limit. |
| `TOO_LONG` | 413 | no | none | The media is longer than your plan allows. The error states the limit. Trim it first or use a plan with a higher limit. |
| `UNSUPPORTED_MEDIA` | 415 | no | `streams` | The file type or streams are not supported by this tool. Convert the file first. Call `GET /v1/capabilities` for the accepted formats. |
| `NOT_HEARD` | 422 | no | none | No speech was found in the audio. Check that the file has speech and a sound track. |
| `TOO_SHORT` | 422 | no | none | The input is shorter than this tool needs. Send a longer input. |
| `SOURCE_REFUSED` | 422 | no | `unreachable`, `not_a_file`, `video_platform`, `private_address`, `too_many_redirects` | We could not take the input from that URL. Read `reason`. Use a direct link to a public media file, or upload the file. |
| `PART_CORRUPT` | 422 | no | none | An uploaded part failed its check. Send that part again. |
| `CONTENT_REFUSED` | 422 | no | `S1`, `S2`, `S3`, `S4`, `S5`, `S6`, `S7`, `S8`, `S9`, `S10`, `S11`, `S12`, `S13`, `S14`, `impersonation`, `blocked_hash`, `vendor_policy` | The content is not allowed by our content policy. Read `reason`. If an `appeal_url` is present, use it to appeal. |
| `CHECKOUT_UNAVAILABLE` | 422 | later | none | Checkout cannot start now. Try again later. |
| `RATE_LIMITED` | 429 | Retry-After | `requests`, `concurrent_jobs` | You sent too many requests or have too many jobs running. Wait the number of seconds in `Retry-After`, then retry. |
| `BUSY` | 503 | Retry-After | `queue_full`, `vendor_throttled`, `subject_moving`, `moderation_unavailable` | The service is busy. Wait the number of seconds in `Retry-After`, then retry. You are not charged. |
| `UNAVAILABLE` | 503 | later | `feature_off`, `vendor_down`, `vendor_quota`, `maintenance` | A feature or vendor is down. Try again later. You are not charged. |
| `FAILED` | 500 | one retry | `timeout`, `admission_aborted` | The job failed on our side. Retry once. If it fails again, contact support with the `requestId`. You are not charged. |
