Error codes

Four things answer you with a code. The command line, the penv.cloud API, the endpoint your identity provider writes to, and the AWS connect callback. Each has its own shape, and each shape is below with the codes it can carry.

What penv prints

A refusal is one object on stderr, with the same three members every time.

{
  "error": "no_credential",
  "message": "penv has no credential for this host.",
  "fix": "Run penv login, or set PENV_TOKEN."
}

message says what happened. fix says the one thing to do next. A refusal that has to be replayed carries what the replay needs beside those three, so approval_required also carries approval, url and expiresAt.

At a terminal the same refusal reads as one line: error:, the message, then the fix. The JSON form is what you get when stdout is not a terminal, when you pass --json, or when penv detects an agent.

Exit codes

penv run is the exception worth knowing: once the child starts, penv leaves with the child's exit code rather than its own.

Every code the command line answers with

bad_url covers four shapes of PENV_URL. penv accepts https anywhere, and plain http only for 127.0.0.1, localhost and [::1]. It refuses plain http to any other host, an address carrying a user in front of its host, an address naming no host at all, and any scheme other than those two.

The refusals penv upgrade can answer with are on upgrade penv, with what to do about each one.

What penv.cloud answers

Every route under /api/v1 answers JSON, and an error body is { "error": "<code>" }. The two schema-shaped refusals add a detail member saying which part of the body was wrong.

Anything else in the 500s is retried once after a second, and then reported as server_error naming the status.

The four approval codes

penv reveal under an agent goes through a person. The state of that request is always a 409, and the code says which of the four states it is in.

approval_denied, approval_expired and approval_redeemed live on both sides: the server sends each one on the 409, and penv prints it back under the same name with the exit code above. approval_pending is the one that changes name, because penv turns it into approval_required and hands you the page and the expiry with it. Two codes are penv's alone. A 404 from the redeem route becomes no_approval, and approval_mismatch is raised before penv ever asks the server to spend the id.

An id that covers another key never gets spent: penv reads the approval before it redeems and refuses with its own approval_mismatch. See coding agents for the whole flow.

Your identity provider

The endpoint your directory writes to speaks RFC 7644 rather than the shape above, because that is what Okta and Entra parse. The body is a SCIM error object, status is a string, and scimType carries one of the RFC's detail keywords when there is one.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "A user with that userName already exists."
}

The content type is application/scim+json;charset=UTF-8. A throw nobody recognized becomes a 500 whose detail is always the same sentence, "The request could not be completed.", because the alternative is handing a stack trace to whoever holds a directory token.

The AWS connect callback

The callback your CloudFormation stack posts to answers a closed set of six, and one mapper decides which. A fresh create answers 200 with the lifecycle secret, a replayed create answers 200 with an empty object, and every other success is 204 with no body.

Next: global options.