Skip to main content
The API uses standard HTTP status codes and returns detailed error information in JSON format.

​
HTTP Status Codes

CodeMeaningWhen it occurs
200SuccessRequest completed successfully
201CreatedResource created successfully
202AcceptedRequest accepted for async processing
204No ContentSuccessful deletion (no response body)
400Bad RequestInvalid request parameters
401UnauthorizedMissing or invalid authentication
403ForbiddenAuthenticated but not authorized
404Not FoundResource does not exist
409ConflictInvalid state transition or concurrent modification
422Validation ErrorRequest body failed validation
500Server ErrorInternal server error

​
Error Response Format

All error responses follow this structure: 
{
  "detail": "Human-readable error message"
}
Validation errors include additional location information: 
{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
Common Errors

​
Authentication Errors (401)

Missing or expired token: 
{
  "detail": "Not authenticated"
}
Solution: Re-authenticate with pragma auth login.

​
Not Found Errors (404)

Resource or build job does not exist: 
{
  "detail": "Resource not found: postgres/database/my-db"
}
Solution: Verify the resource ID exists in your namespace.

​
Conflict Errors (409)

​
Invalid Lifecycle Transition

Attempting an invalid state change: 
{
  "detail": "Cannot transition from PROCESSING to DRAFT"
}
Solution: Wait for the current operation to complete before modifying.

​
Resource In Processing

Modifying a resource while it’s being processed: 
{
  "detail": "Resource is currently being processed and cannot be modified"
}
Solution: Wait for the resource to reach READY or FAILED state.

​
Validation Errors (422)

​
Missing Required Fields

{
  "detail": [
    {
      "loc": ["body", "provider"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
Solution: Include all required fields in your request.

​
Dependency Validation Failed

Dependencies don’t exist or aren’t ready: 
{
  "detail": "Dependency validation failed: postgres/database/missing-db does not exist"
}
Solution: Ensure all dependencies exist and are in READY state.

​
Field Reference Resolution Failed

A field reference points to a non-existent output: 
{
  "detail": "Field reference failed: postgres/database/my-db does not have output 'connection_string'"
}
Solution: Verify the referenced resource exists and has the expected outputs.

​
Build Errors (400/404)

​
Build Job Not Found

{
  "detail": "Build job not found: build-abc123"
}
Solution: Verify the job name from the push response.

​
Build Creation Failed

{
  "detail": "Failed to create build job"
}
Solution: Check that the provider code archive is valid.

​
Deployment Errors (404/500)

​
Deployment Not Found

{
  "detail": "Deployment not found: provider-my-provider"
}
Solution: Deploy the provider first with the deploy endpoint.

​
Lifecycle State Reference

Understanding lifecycle states helps interpret errors:
StateDescriptionCan Modify?
draftInitial state, not yet committedYes
pendingCommitted, waiting to be processedNo
processingCurrently being handled by a providerNo
readySuccessfully processedYes
failedProcessing failed, error recordedYes

​
Best Practices

  1. Check response status codes before parsing the body
  2. Retry with backoff for 5xx errors
  3. Don’t retry 4xx errors without fixing the request
  4. Poll status endpoints for async operations (builds, deployments)
  5. Log correlation IDs from responses for debugging