Errors

Eventlayer uses standard HTTP status codes and a stable error code for each kind of failure. Every error code always has the same HTTP status and title.

Error schema

Errors use an error object inside the standard API response envelope:

{
  "status": 422,
  "error": {
    "type": "https://eventlayer.dev/docs/errors#validation-failed",
    "title": "Request validation failed",
    "status": 422,
    "code": "VALIDATION_FAILED",
    "detail": "One or more fields are invalid.",
    "requestId": "req_01k2example",
    "fields": [
      {
        "field": "endsAt",
        "message": "The end time must be after the start time."
      }
    ]
  }
}

Handling errors with TypeScript

The TypeScript SDK returns API failures as data rather than throwing them:

const {
  data: ticket,
  error,
  response,
} = await eventlayer.tickets.checkIn({ ticketId: "tkt_123" });

if (error) {
  switch (error.code) {
    case "TICKET_ALREADY_CHECKED_IN":
      // This operation was already completed.
      break;
    case "VALIDATION_FAILED":
      for (const field of error.fields) {
        console.error(field.field, field.message);
      }
      break;
    case "RATE_LIMIT_EXCEEDED":
      console.error(response.headers.get("retry-after"));
      break;
    default:
      console.error(error.requestId, error.detail);
  }
} else {
  console.log(ticket.status);
}

Network failures where no HTTP response is received still throw.

Error reference

INVALID_REQUEST

• Status: 400 Bad Request
• Message: The request could not be parsed or understood.
• Suggested action: Check the request syntax, JSON body, and query-string encoding before retrying.

AUTHENTICATION_REQUIRED

• Status: 401 Unauthorized
• Message: The operation requires authentication using one of its supported authentication schemes.
• Suggested action: Supply the bearer credential documented for the endpoint. Dashboard-only operations require a valid dashboard session.

INVALID_API_KEY

• Status: 401 Unauthorized
• Message: The supplied API key is invalid, expired, or revoked.
• Suggested action: Check the Authorization: Bearer header or create a replacement key. See Authentication.

PASS_TOKEN_INVALID

• Status: 401 Unauthorized
• Message: The supplied Apple Wallet pass token is invalid.
• Suggested action: Generate a new signed pass URL instead of modifying or reusing the invalid token.

PASS_TOKEN_EXPIRED

• Status: 401 Unauthorized
• Message: The supplied Apple Wallet pass token has expired.
• Suggested action: Generate a new signed pass URL and retry the download.

NOT_FOUND

• Status: 404 Not Found
• Message: The directly addressed resource could not be found.
• Suggested action: Verify the resource ID and account scope. Eventlayer may return the same error when a resource exists outside the authenticated account.

ROUTE_NOT_FOUND

• Status: 404 Not Found
• Message: The requested API route does not exist.
• Suggested action: Check the base URL, API path, and SDK version.

METHOD_NOT_ALLOWED

• Status: 405 Method Not Allowed
• Message: The HTTP method is not supported by the requested route.
• Suggested action: Use the method documented in the API reference or call the corresponding SDK resource method.

FAILED_PRECONDITION

• Status: 409 Conflict
• Message: The target resource does not satisfy a prerequisite for the operation.
• Suggested action: Read detail and fields, update the resource state or configuration, and retry. For example, an event must have a ticket type before tickets can be issued.

TICKET_ALREADY_CHECKED_IN

• Status: 409 Conflict
• Message: The ticket has already been checked in.
• Suggested action: Treat the check-in as already completed or show the existing check-in state. Do not repeatedly retry the mutation.

UNSUPPORTED_MEDIA_TYPE

• Status: 415 Unsupported Media Type
• Message: The request uses a content type that the endpoint does not accept.
• Suggested action: Use the Content-Type documented for the endpoint. JSON requests normally use application/json; image uploads use multipart form data.

VALIDATION_FAILED

• Status: 422 Unprocessable Content
• Message: One or more submitted fields or references are invalid for the operation.
• Suggested action: Use the fields array to associate each message with the corresponding request field, correct the values, and retry.

PAYLOAD_TOO_LARGE

• Status: 413 Content Too Large
• Message: The request or uploaded image exceeds the permitted size.
• Suggested action: Reduce or compress the payload before retrying.

RATE_LIMIT_EXCEEDED

• Status: 429 Too Many Requests
• Message: The API key has exceeded its request rate.
• Suggested action: Respect the Retry-After response header and reduce concurrency. See Rate Limits.

REQUEST_TIMEOUT

• Status: 408 Request Timeout
• Message: Eventlayer could not complete the request within the permitted time.
• Suggested action: Retry with backoff. Use an idempotency key when retrying supported mutations.

INTERNAL_SERVER_ERROR

• Status: 500 Internal Server Error
• Message: Eventlayer could not complete the request because of an unexpected server failure.
• Suggested action: Retry with backoff. If the problem continues, contact support and include requestId.

Status code summary

Next steps