Introduction
Lemonway APIs use standard HTTP response status codes to indicate whether a request was successful or could not be processed.
The HTTP status code provides the general result of the request. When an error occurs, the response body may also contain a Lemonway-specific error code and message that provide additional information.
For the complete list of Lemonway functional error codes, see Complete Lemonway Error List.
Successful responses
| Status code | Description | Typical usage |
|---|---|---|
200 OK | The request was successfully processed. | Retrieving or updating a resource |
201 Created | The request was successfully processed and a new resource was created. | Creating an account, wallet, or other resource |
Client error responses
Client errors indicate that the request could not be completed because of the request, authentication, permissions, or the current state of a resource.
| Status code | Description | Typical causes | Recommended action |
|---|---|---|---|
400 Bad Request | The request is invalid or contains incorrect parameters. | Missing parameters, invalid formats, invalid values, or malformed request data | Check the request structure, parameter names, formats, and required fields |
401 Unauthorized | The request is not authenticated. | Missing, invalid, or expired API key or bearer token | Check the authentication header and generate a new token if necessary |
403 Forbidden | The request is authenticated but not authorised. | Insufficient permissions or functionality not enabled for the account | Check the account permissions and contract configuration |
404 Not Found | The requested resource could not be found. | Invalid resource identifier or resource unavailable in the current environment | Check the identifier and confirm that the resource exists |
409 Conflict | The request conflicts with the current state of a resource. | The resource already exists or the requested operation conflicts with an existing resource | Check the current resource state before retrying |
500 Internal Server Error | The server encountered an unexpected error while processing the request. | Unexpected technical failure | Retry later and contact Lemonway Support if the error persists |
NoteThe statuses listed above should be kept aligned with the statuses actually returned by each Lemonway API. Some endpoints may support additional statuses.
Response body
When an error occurs, the response body may contain additional information, including:
- A Lemonway-specific error code
- An error message
- The parameter or resource that caused the error
- A request or correlation identifier, if available
The HTTP status code and the Lemonway error code should be interpreted together. For example, a 400 status indicates that the request is invalid, while the Lemonway error code explains the specific validation or business rule that was not satisfied.
Examples
Successful response
A successful response may return HTTP 200 or 201, depending on the operation.
{
"id": "resource-id",
"status": "CREATED"
}Bad request
{
"code": "ERROR_CODE",
"message": "The request contains invalid data"
}The exact response fields and error-code format may differ between API versions and endpoints. Always use the response schema documented for the relevant endpoint.
Conflict
A 409 Conflict response indicates that the request cannot be completed because it conflicts with an existing resource or the current state of the resource.
For example, the account creation API may return 409 when an account with the same identity already exists. See the endpoint-specific documentation for the exact response and resolution.
Troubleshooting an error
When troubleshooting an unsuccessful request:
- Check the HTTP status code.
- Read the error code and message in the response body.
- Confirm that the request is being sent to the correct environment.
- Check authentication, required parameters, data formats, and resource identifiers.
- Consult the endpoint-specific error documentation.
- Search the Complete Lemonway Error List.
- If the issue persists, contact Lemonway Support and provide:
- The HTTP method and endpoint
- The HTTP status code
- The Lemonway error code and message
- The timestamp of the request
- The environment used
- The request or correlation identifier, if returned
NoteDo not include API keys, bearer tokens, passwords, or unnecessary personal data when reporting an error.

