> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retempo.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Retempo API Error Codes and Troubleshooting Guide
> Reference for Retempo API error codes, error messages, and fixes. Covers 400 validation, 404 not found, 409 conflict, and 500 server errors.
Retempo returns JSON error objects with an `error` field on every non-successful response. The `error` value is a human-readable string that describes what went wrong. Use the HTTP status code to quickly classify the problem, then read the `error` message to understand the specific cause.
```json theme={null}
{ "error": "name is required." }
```
Use this reference to identify the root cause and apply the correct fix before retrying your request.
## HTTP Status Codes
### 400 Bad Request
A `400` response means your request contained invalid input, was missing a required field, or violated a constraint. The `error` message will identify the specific field or rule that failed. Correct the request body and retry.
| Error Message | Cause | Fix |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `"name is required."` | You submitted a create request without the `name` field. | Add the `name` field to your request body. |
| `"billingInterval must be one of: MONTH, WEEK, DAY, NONE."` | You passed an unrecognized value for `billingInterval`. | Use one of the accepted values: `MONTH`, `WEEK`, `DAY`, or `NONE`. |
| `"Invoices cannot be created as PAID without a real payment event."` | You attempted to create an invoice with status `PAID` directly, bypassing the settlement flow. | Create the invoice as `DRAFT` or `OPEN`, then submit a settlement to advance it to `PAID`. |
| `"Settlement payer must match the invoice user."` | The `payerId` on the settlement does not match the subscriber recorded on the invoice. | Verify that the `payerId` you are submitting matches the subscriber's user ID on the invoice. |
| `"Settlement merchant must match the service owner."` | The `merchantId` on the settlement does not match the owner of the service that issued the invoice. | Verify that the `merchantId` matches the `ownerId` of the service. |
| `"Checkout sessions can only be created with PENDING status."` | You passed a `status` value other than `PENDING` when creating a checkout session. | Omit the `status` field or set it to `PENDING` — checkout sessions always start in `PENDING`. |
| `"billingInterval must be NONE for ONE_TIME pricing."` | You set `pricingType` to `ONE_TIME` but specified a recurring `billingInterval`. | Set `billingInterval` to `NONE` when using the `ONE_TIME` pricing type. |
| `"amount must be greater than zero."` | You submitted a settlement or invoice with an amount of `0`. | Provide a positive non-zero USDC amount. |
| `"A referenced database record does not exist."` | Your request referenced an ID — such as a `userId`, `serviceId`, or `paymentPlanId` — that does not exist. | Confirm each referenced ID exists before submitting the request. |
### 404 Not Found
A `404` response means Retempo could not find the resource you referenced. This usually means the ID is incorrect, the resource belongs to a different service, or it has not been created yet.
| Error Message | Cause | Fix |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `"Service was not found."` | The service ID in your request does not match any existing service. | Double-check the service ID and confirm the service exists in your dashboard. |
| `"Invoice was not found."` | The invoice ID does not match any invoice in the system, or the invoice belongs to a different service. | Verify the `invoiceId` and ensure it belongs to the service you are querying. |
| `"Settlement was not found."` | The settlement ID does not correspond to an existing settlement record. | Re-fetch your settlements list to obtain the correct ID. |
| `"Checkout session was not found."` | The checkout session ID does not match any existing session. | Verify the `checkoutSessionId` and confirm it was created under the correct service. |
| `"Payment plan was not found for the service."` | You referenced a payment plan that does not exist or is not attached to the specified service. | Confirm the payment plan ID and that it was created under the correct service. |
| `"Subscription was not found for the service and user."` | The subscription ID does not correspond to an existing subscription under the given service and user combination. | Re-fetch your subscriptions list to obtain the correct ID and confirm the service and user IDs match. |
| `"Referenced database record was not found."` | A resource referenced in your request body — such as a nested user or related record — does not exist. | Confirm all referenced IDs in your request exist before submitting. |
### 409 Conflict
A `409` response means a record with the same unique key already exists. Retempo enforces uniqueness on certain field combinations to prevent duplicate entries.
| Error Message | Cause | Fix |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `"A database record with these unique fields already exists."` | You attempted to create a resource that conflicts with an existing record (for example, a duplicate settlement for the same invoice and reference hash). | Fetch the existing record instead of creating a new one. If you intended to update it, use the appropriate update endpoint. |
If you receive a `409` on a settlement submission, the settlement may have already been recorded on-chain. Check your settlements list before resubmitting to avoid duplicating a payment.
### 500 Internal Server Error
A `500` response indicates an unexpected server-side error or a failure during on-chain submission to Arc. These errors are not caused by your request format, but you may be able to retry after investigating the underlying issue.
| Error Message | Cause | Fix |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"Internal server error."` | An unexpected error occurred on the server that is not related to your request input. | Retry the request after a brief delay. If the error persists, contact Retempo support. |
| `"Arc settlement transaction failed."` | Retempo submitted the settlement to Arc but the on-chain transaction was rejected or did not complete. | Check the `transactionHash` on the Arc explorer to see the contract-level error. Verify your payer and merchant addresses, the settlement amount, and the reference hash, then resubmit. |
A `500` error from the settlement endpoint sets the settlement status to `FAILED`. Retempo does not automatically retry failed settlements. You must investigate and submit a new settlement record to reattempt payment.
## Arc Contract Errors
When Retempo submits a settlement to Arc, the Arc smart contract validates the transaction before recording it on-chain. Contract-level validation failures surface as `400` or `500` errors from the Retempo API. Use this reference to interpret the underlying cause.
| Arc Error | Meaning | Fix |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `SettlementAlreadyRecorded` | A settlement with the same `invoiceId`, `referenceHash`, and amounts already exists on-chain. Arc rejects duplicate settlement IDs to prevent double-payment. | Fetch your existing settlements to confirm the invoice is already paid. Do not resubmit. |
| `InvalidAddress` | The `payerAddress` or `merchantAddress` is a zero address (`0x0000...0000`). Arc rejects zero addresses. | Provide valid EVM wallet addresses for both `payerAddress` and `merchantAddress`. |
| `InvalidAmount` | The settlement amount is `0`. Arc requires a positive non-zero USDC amount. | Provide a positive non-zero value for the settlement amount. |
| `InvalidTimestamp` | The `occurredAt` timestamp submitted with the settlement is zero or missing. | Provide a valid ISO 8601 UTC timestamp for `occurredAt`. |
| `NotAuthorizedOperator` | The account submitting the settlement to Arc is not registered as an authorized operator. | Contact Retempo support — this indicates a configuration issue with the operator account, not your API request. |
## Troubleshooting
A `FAILED` settlement means the on-chain submission to Arc did not complete successfully. Take the following steps to diagnose and resolve it:
1. **Check the Arc explorer.** Use the `transactionHash` returned with the settlement to look up the transaction on the Arc block explorer. The contract revert reason will tell you exactly which validation rule failed.
2. **Verify your addresses.** Confirm that both `payerAddress` and `merchantAddress` are valid, non-zero EVM addresses. A zero address will cause an `InvalidAddress` rejection.
3. **Verify the amount.** Ensure the settlement amount is greater than zero.
4. **Check for duplicates.** If the Arc error is `SettlementAlreadyRecorded`, the settlement already exists on-chain. Fetch the invoice to confirm it is marked `PAID` — if it is, no further action is needed.
5. **Resubmit.** Once you have identified and corrected the issue, create a new settlement record and submit it. Failed settlements cannot be reactivated.
A `404` on an invoice request means Retempo could not locate the invoice you referenced. Check the following:
* **Verify the `invoiceId`.** Retempo IDs are cuid strings (e.g., `clz1abc2def3...`). Confirm you are using the correct ID and have not truncated or modified it.
* **Check the service scope.** Invoices are scoped to a service. If you are querying invoices for a specific service, ensure the invoice belongs to that service and not a different one.
* **Confirm the invoice exists.** Fetch the full list of invoices for your subscription to see all available invoice IDs.
A `409` means a record with the same unique key already exists in Retempo. Rather than creating a duplicate, fetch the existing record:
* **For settlements:** Query your settlements list filtered by `invoiceId` to retrieve the existing settlement. Check its status before deciding whether to take further action.
* **For other resources:** Use the list or get endpoint for that resource type to retrieve the existing record by its unique fields.
If you genuinely need a separate record (for example, a corrected settlement after a failed one), ensure the new record uses a different `referenceHash` or unique identifier as appropriate.