Blog Twitter Facebook Product Hunt LinkedIn GitHub Jumbo
API ReferenceCoreError handling

Error handling

We use conventional HTTP status codes to indicate the success or failure of an API request. In general:

  • Codes in the `2xx` range indicate success.
  • Codes in the `4xx` range indicate a client-side error (e.g., a required parameter was omitted, invalid data was sent, etc.).
  • Codes in the `5xx` range indicate an error with our servers (these are rare), in case of doubt you can visit our status page.

When an API request fails (returns a `4xx` or `5xx` status code), the response body will contain a JSON object detailing the error.

Error response structure

All error responses follow a consistent JSON format:

Example of an error response
{
  "error": {
    "message": "A human-readable description of the error.",
    "details": "Optional: Additional details or structured information about the error."
  }
}
PropertyTypeDescription
`error``object`Container for the error information.
`message``string`A brief, human-readable summary of the error.
`details``string` or `object`Optional. Provides more specific context or structured data about the error (e.g., validation failures, conflicting resources).

HTTP status codes

Here are some common HTTP status codes you might encounter:

CodeStatusMeaning
`200`OKThe request was successful.
`201`CreatedThe request was successful and a resource was created (e.g., creating a webhook).
`204`No ContentThe request was successful but there is no representation to return (e.g., deleting a webhook).
`400`Bad RequestThe request was unacceptable, often due to missing a required parameter or invalid data format.
`401`UnauthorizedNo valid API key provided.
`403`ForbiddenThe API key doesn’t have permissions to perform the request.
`404`Not FoundThe requested resource doesn’t exist.
`409`ConflictThe request conflicts with the current state of the resource (e.g., duplicate webhook URL).
`429`Too Many RequestsRate limits have been exceeded.
`500`Internal Server ErrorSomething went wrong on lomi’s end (these are rare).
`503`Service UnavailableWe’re temporarily offline for maintenance. Please try again later.

Common error messages

While the specific `message` and `details` will vary, here are examples associated with common status codes:

`400` Bad Request:

  • "message": "Invalid request", "details": "Missing required field: \url`”`
  • "message": "Invalid request", "details": "Invalid \Webhook ID` format.”`
  • "message": "Invalid request body"

`401` Unauthorized:

  • "message": "Invalid API key", "details": "The provided API key is invalid or does not exist"
  • "message": "Missing API key", "details": "API key is required for authentication"
  • "message": "Authentication required"

`404` Not Found:

  • "message": "Webhook not found", "details": "Webhook with ID \wh_…` does not exist or does not belong to this organization.”`
  • "message": "Resource not found"

`409` Conflict:

  • "message": "Conflict", "details": "A webhook with this URL already exists for your organization."

`429` Too Many Requests:

  • "message": "Rate limit exceeded"

`500` Internal Server Error:

  • "message": "Internal server error"
  • "message": "Database error", "details": "Failed to execute database query."

Handling errors

Your integration should gracefully handle potential API errors:

  1. Check the HTTP Status Code: Determine the general outcome of the request.
  2. Parse the Response Body: If the status code indicates an error (`4xx` or `5xx`), parse the JSON response body.
  3. Use Error Information: Use the `message` and `details` from the parsed JSON to understand the specific problem.
  4. Implement Logic: Based on the error type, implement appropriate logic (e.g., prompt the user to fix input for a `400` error, check credentials for `401`, retry later for `429` or `5xx` errors).
  5. Log Errors: Log errors, including the full response body and potentially the request ID (if provided in headers), to aid debugging.
AuthenticationData models