Retempo API Error Codes and Troubleshooting Guide

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.

{ "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

My settlement came back FAILED

A FAILED settlement means the on-chain submission to Arc did not complete successfully. Take the following steps to diagnose and resolve it:

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.
Verify your addresses. Confirm that both payerAddress and merchantAddress are valid, non-zero EVM addresses. A zero address will cause an InvalidAddress rejection.
Verify the amount. Ensure the settlement amount is greater than zero.
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.
Resubmit. Once you have identified and corrected the issue, create a new settlement record and submit it. Failed settlements cannot be reactivated.

I got a 404 for my invoice

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.

I got a 409 Conflict

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.

Get Started

Core Workflows

Usage Billing

Onchain Settlement

Reference

Retempo API Error Codes and Troubleshooting Guide

HTTP Status Codes

400 Bad Request

404 Not Found

409 Conflict

500 Internal Server Error

Arc Contract Errors

Troubleshooting

​HTTP Status Codes

​400 Bad Request

​404 Not Found

​409 Conflict

​500 Internal Server Error

​Arc Contract Errors

​Troubleshooting

HTTP Status Codes

400 Bad Request

404 Not Found

409 Conflict

500 Internal Server Error

Arc Contract Errors

Troubleshooting