Skip to main content
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 MessageCauseFix
"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 MessageCauseFix
"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 MessageCauseFix
"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 MessageCauseFix
"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 ErrorMeaningFix
SettlementAlreadyRecordedA 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.
InvalidAddressThe payerAddress or merchantAddress is a zero address (0x0000...0000). Arc rejects zero addresses.Provide valid EVM wallet addresses for both payerAddress and merchantAddress.
InvalidAmountThe settlement amount is 0. Arc requires a positive non-zero USDC amount.Provide a positive non-zero value for the settlement amount.
InvalidTimestampThe occurredAt timestamp submitted with the settlement is zero or missing.Provide a valid ISO 8601 UTC timestamp for occurredAt.
NotAuthorizedOperatorThe 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.