Skip to content
Rival Docs

Execution Layer

When someone calls a Rival tool, the platform handles everything between the incoming request and the response - routing, validation, running your code, logging the result, and deducting the cost. You write the handler; Rival takes care of the rest.

The execution model

Rival tools are stateless. Each execution is completely independent - there is no memory, cache, or shared state carried between calls. Every invocation starts fresh with only the input you provide and the environment variables attached to the tool.

This design keeps tools predictable and scalable. A tool called once behaves identically to the same tool called a thousand times in parallel, because each execution is isolated from all the others.

Rival handles all routing and scaling automatically. You do not configure servers, set concurrency limits, or manage capacity. If your tool gets called frequently, the platform handles it. If it sits idle for weeks and then gets a burst of calls, that works too.

What happens when a tool is invoked

From a user’s perspective, the lifecycle of a single execution looks like this:

1. The request arrives

A caller sends a POST request to the invocation endpoint with their API key in the Authorization header, the function ID and version in the URL, and the input payload in the request body.

2. Rival validates the request

Before your code runs, the platform checks four things:

  • API key - is the key valid and does it belong to an organization with access to this tool?
  • Balance - does the organization have enough credits to pay for this execution?
  • Function ID - does this tool exist?
  • Version - does the requested version exist?

If any of these checks fail, the request is rejected immediately with an appropriate error code and your code never runs. Importantly, a rejected request is not charged.

3. Your handler runs

Once validation passes, Rival runs your tool’s handler with the input payload injected as the event argument. Your code executes and returns a response object containing a statusCode and a body.

4. The result is returned and logged

The platform sends the response back to the caller and logs the execution - recording the input, output, credits consumed, and status. The log is immediately visible in your analytics dashboard.

Error conditions

Not every execution completes successfully. The platform distinguishes between several types of failure:

401 Unauthorized - the API key is missing or invalid. The request is rejected before any processing occurs.

402 Payment Required - the organization does not have enough credits. Execution is blocked and no charge is made. Top up your balance from Settings → Billing in Dashboard.

404 Not Found - the function ID or version does not exist. Check that you are using the correct values from the tool’s detail page.

408 Timeout - your handler ran longer than the configured timeout limit. The execution is terminated, and the caller receives a timeout response. Timeout executions are not charged.

500 Handler Error - your handler threw an uncaught exception. The platform catches it, returns a 500 status code in the response body, and logs the error. The execution is charged because your code did run.

What you do not manage

Rival abstracts away the infrastructure so you can focus on building. You do not manage:

  • Server provisioning or capacity planning
  • Scaling or load balancing
  • Execution isolation between users
  • Credit accounting and billing logic
  • Execution logging and retention

All of that is handled by the platform. Your job is to write a handler that takes an input and returns an output.