Skip to main content
The Penbox API uses conventional HTTP status codes to indicate the success or failure of a request. The same set of codes applies consistently across all endpoints — creating a Case behaves the same way as any other call.

​
Success codes

CodeNameDescription
200OKThe request succeeded. Returned for reads, updates, and for creating a Case (POST /cases).
201CreatedA resource was created successfully (e.g. attachment upload, document intelligence).
202AcceptedThe request was accepted and will be processed asynchronously (e.g. webhooks / events).

​
Client error codes (4xx)

CodeNameDescription
400Bad RequestThe request is invalid: a required field is missing, the JSON is malformed, a UUID or email is invalid, a schema value is incorrect, or a referenced template/owner could not be found.
401UnauthorizedAuthentication failed: the Authorization header is missing, or the token/JWT is invalid or expired.
403ForbiddenAuthenticated but not allowed: the token does not have access to the requested workspace or resource.
404Not FoundThe resource does not exist (unknown id for a case, template, workspace, form…) or the endpoint does not exist.
409ConflictThe request conflicts with the current state of the resource (e.g. a step already started, a duplicate).
413Payload Too LargeThe request body is too large (e.g. a file upload exceeding the size limit).
422Unprocessable EntityThe request is well-formed but fails a business validation rule.

​
Server error codes (5xx)

CodeNameDescription
500Internal Server ErrorAn unexpected error occurred on our side.
502Bad GatewayA backend service is unreachable or returned an error.
503Service UnavailableThe service is temporarily unavailable (infrastructure level).
504Gateway TimeoutThe request took too long to complete (timeout ≈ 30 s).
429 Too Many Requests is not produced by the application itself, but may be returned by the network / gateway layer if rate limiting is in effect.

​
Error response body

All error responses share the same JSON structure: 
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "A human-readable description of the error",
  "errors": [
    {
      "message": "validation detail",
      "path": ["field"],
      "type": "..."
    }
  ]
}
FieldDescription
statusCodeThe HTTP status code, repeated in the body for convenience.
errorThe official HTTP status name (e.g. Bad Request).
messageA human-readable description of what went wrong.
errorsPresent only for validation errors (400). An array detailing each invalid field.
When handling errors programmatically, branch on the HTTP statusCode rather than parsing the message, which is meant for humans and may change.