General HTTP Response Codes

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 codeDescriptionTypical usage
200 OKThe request was successfully processed.Retrieving or updating a resource
201 CreatedThe 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 codeDescriptionTypical causesRecommended action
400 Bad RequestThe request is invalid or contains incorrect parameters.Missing parameters, invalid formats, invalid values, or malformed request dataCheck the request structure, parameter names, formats, and required fields
401 UnauthorizedThe request is not authenticated.Missing, invalid, or expired API key or bearer tokenCheck the authentication header and generate a new token if necessary
403 ForbiddenThe request is authenticated but not authorised.Insufficient permissions or functionality not enabled for the accountCheck the account permissions and contract configuration
404 Not FoundThe requested resource could not be found.Invalid resource identifier or resource unavailable in the current environmentCheck the identifier and confirm that the resource exists
409 ConflictThe request conflicts with the current state of a resource.The resource already exists or the requested operation conflicts with an existing resourceCheck the current resource state before retrying
500 Internal Server ErrorThe server encountered an unexpected error while processing the request.Unexpected technical failureRetry later and contact Lemonway Support if the error persists

Note

The 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:

  1. Check the HTTP status code.
  2. Read the error code and message in the response body.
  3. Confirm that the request is being sent to the correct environment.
  4. Check authentication, required parameters, data formats, and resource identifiers.
  5. Consult the endpoint-specific error documentation.
  6. Search the Complete Lemonway Error List.
  7. 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

Note

Do not include API keys, bearer tokens, passwords, or unnecessary personal data when reporting an error.