API Errors

General provisions

Merchant API returns errors in a common format.

The merchant should handle errors safely: show a clear message to the buyer, save trace_id in backend logs and never expose the secret API key.

trace_id is needed for diagnostics. If you contact support, include trace_id, request time and endpoint.

Error format

An error contains the main fields:

• success;
• message;
• error.code;
• error.details;
• trace_id.

success will be false.

message contains a short error description.

error.code contains a stable error code.

error.details may contain additional details, for example field validation errors.

trace_id helps identify a specific request during troubleshooting.

What to log

On the merchant side, it is useful to log:

• endpoint;
• HTTP method;
• HTTP status;
• error.code;
• message;
• trace_id;
• your own order_id, if available.

Do not log the full secret API key.

Authentication errors

API_KEY_REQUIRED

Code API_KEY_REQUIRED means API did not receive Bearer token.

Check the header:

Authorization: Bearer weelay_secret_...

API_KEY_INVALID_FORMAT

Code API_KEY_INVALID_FORMAT means the key has invalid format.

Secret key must start with weelay_secret_.

API_KEY_INVALID

Code API_KEY_INVALID means the key was not found or is incorrect.

Check that you use the current secret API key from the project dashboard.

API_KEY_REVOKED

Code API_KEY_REVOKED means the key was revoked.

Create a new secret API key in the project dashboard and update backend settings.

PROJECT_NOT_ACTIVE

Code PROJECT_NOT_ACTIVE means the project is inactive.

Check project status in the dashboard.

ACCOUNT_NOT_ACTIVE

Code ACCOUNT_NOT_ACTIVE means the account is inactive.

Check account status or contact support.

Validation errors

VALIDATION_ERROR

Code VALIDATION_ERROR means request data did not pass validation.

Most often this is related to incorrect amount, too long order_id, invalid status, limit or page.

Check error.details.

For invoice creation, amount must be a positive string with max 2 decimals.

Access and lookup errors

FORBIDDEN

Code FORBIDDEN means the action is forbidden.

Check that the request uses the correct key and the correct project.

NOT_FOUND

Code NOT_FOUND means the resource was not found.

For example, an invoice with the specified id does not exist or does not belong to the current project.

Check invoice id and project secret API key.

METHOD_NOT_ALLOWED

Code METHOD_NOT_ALLOWED means the endpoint does not support the selected HTTP method.

Check that you use the correct method: GET or POST.

Rate limits

RATE_LIMITED

Code RATE_LIMITED means too many requests were sent.

HTTP status is usually 429.

In this case, the merchant backend should wait and retry later if retry is acceptable for the scenario.

Do not repeat the request endlessly without delay.

Internal error

INTERNAL_SERVER_ERROR

Code INTERNAL_SERVER_ERROR means an internal server error occurred.

The merchant should save trace_id and retry later if this is safe.

If the error repeats, contact support and include trace_id.

Invoice creation errors

When creating an invoice, possible errors include:

• invalid amount;
• missing amount;
• too long order_id;
• exceeded limit;
• inactive project;
• invalid API key.

If invoice creation failed, do not show an old or random payment_url to the buyer.

First receive a successful response from Weelay.

Invoice retrieval errors

When retrieving an invoice, possible errors include:

• invoice not found;
• invoice belongs to another project;
• invalid secret API key;
• request limit exceeded.

Check invoice id, project and API key.

How to show the error to the buyer

The buyer does not need to see technical API error codes.

It is better to show a simple message:

Could not create the payment page. Please try again later or contact the merchant.

Technical details should remain in merchant logs.

How to handle an error in backend

Recommended order:

1. Get HTTP status.
2. Read error.code.
3. Save trace_id.
4. Save your own order_id, if available.
5. Do not log the secret API key.
6. Decide whether the request can be safely retried.
7. Show a clear message to the buyer.

When a request can be retried

A request can be retried later if the error is temporary, for example RATE_LIMITED or INTERNAL_SERVER_ERROR.

When retrying invoice creation, use the same Idempotency-Key if it is the same invoice creation operation.

If the error is VALIDATION_ERROR, fix request data first.

If the error is authentication-related, fix API key or project status first.

Production checklist

Before launch, check:

• backend saves trace_id;
• errors do not expose the secret API key;
• the buyer sees a clear message;
• VALIDATION_ERROR is handled separately;
• RATE_LIMITED does not cause endless retry without delay;
• retrying invoice creation uses the same Idempotency-Key;
• support can find the order by order_id and trace_id.

Summary

API errors should be handled predictably.

Main fields for the merchant: error.code, error.details and trace_id.

Main security rule: do not log or display the full secret API key.