Skip to main content
All errors return a consistent JSON body with an error code and a human-readable message.

​
Error format

{
  "error": "error_code",
  "message": "Human-readable description of what went wrong"
}

​
Error codes

HTTP StatusError CodeDescription
400validation_errorThe request body or parameters are invalid
401unauthorizedThe API key is missing, invalid, or revoked
402insufficient_creditsNot enough credits to run the requested operation
403forbiddenThe API key does not have the required scope
404not_foundThe requested deployment, thread, or run does not exist
409deployment_not_readyThe deployment is still provisioning
422invalid_skillA skill file could not be fetched or parsed
422invalid_secret_refA secret reference does not exist or is not accessible
429rate_limitedToo many requests — back off and retry
500server_errorAn unexpected error occurred on the server

​
Common scenarios

​
Missing API key

curl https://api.prismagents.com/v1/deployments
# 401: { "error": "unauthorized", "message": "Invalid or missing API key" }

​
Deployment still provisioning

curl https://api.prismagents.com/v1/deployments/dep_7xK9s2/messages \
  -X POST \
  -H "Authorization: Bearer $PRISM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Hello" }'
# 409: { "error": "deployment_not_ready", "message": "Deployment is provisioning. Poll GET /v1/deployments/dep_7xK9s2 until status is ready" }

​
Unknown secret reference

# Creating a deployment with "META_ADS_TOKEN": "sec_does_not_exist"
# 422: { "error": "invalid_secret_ref", "message": "Secret reference 'sec_does_not_exist' not found" }

​
Deployment not found

curl https://api.prismagents.com/v1/deployments/dep_nonexistent \
  -H "Authorization: Bearer $PRISM_API_KEY"
# 404: { "error": "not_found", "message": "Deployment not found" }